Skip to content

Commit 6ea801b

Browse files
wangfang1claude
wangfang1
and
claude
committed
fix: 修复节点列表加载、lint 快捷键提示及 Composer 侧边栏自动展开
- 修复 /api/nodes 返回格式变更后前端未适配导致 palette 始终为空的问题 - 将 pipelineTranslations 传递给 mergeNodeWithPalette 以支持节点翻译 - 折叠的 lint 警告横幅增加 ? 快捷键提示按钮 - 提交 Composer 内容时自动展开 AI 侧边栏 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent be29689 commit 6ea801b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

67 files changed

+2952
-2221
lines changed

‎.claude/settings.local.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(npm run:*)",
5+
"Bash(git checkout:*)",
6+
"Bash(grep -r \"50\\\\|90\\\\|offset.*node\\\\|position.*offset\" /Users/bigo/Documents/AIProject/AgentFlow/bin/lib/*.mjs)",
7+
"Bash(grep -rn \"400\\\\|220\" /Users/bigo/Documents/AIProject/AgentFlow/bin/lib/*.mjs)",
8+
"Bash(grep:*)",
9+
"Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('builtin/web-ui/src/i18n/locales/zh/flow.json','utf8'\\)\\); console.log\\('zh OK'\\)\")",
10+
"Bash(node -e \"JSON.parse\\(require\\('fs'\\).readFileSync\\('builtin/web-ui/src/i18n/locales/en/flow.json','utf8'\\)\\); console.log\\('en OK'\\)\")",
11+
"Bash(ls package.json vite.config.*)",
12+
"Bash(node -e \"const p=require\\('./package.json'\\); console.log\\(Object.keys\\(p.scripts||{}\\).join\\(', '\\)\\)\")",
13+
"Bash(npx vite:*)",
14+
"Bash(python3 -c \"import sys,json; d=json.loads\\(sys.stdin.read\\(\\)\\); print\\(d.get\\('message',{}\\).get\\('content',[{}]\\)[0].get\\('text',''\\)[:200] if isinstance\\(d.get\\('message',{}\\).get\\('content',[{}]\\)[0], dict\\) else 'tool_use'\\)\")",
15+
"Bash(python3 -c ':*)",
16+
"Bash(node -e ':*)",
17+
"Bash(git add:*)"
18+
]
19+
}
20+
}

‎CLAUDE.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# AgentFlow Project Guidelines
2+
3+
## Project Overview
4+
5+
AgentFlow is an orchestration system for long-running complex agent tasks. It uses graphs to encode dependencies and control flow, treating Cursor, OpenCode, and Claude Code as swappable execution backends.
6+
7+
**Core Philosophy:**
8+
- **Orchestration, Not Dialogue**: Describe workflows with nodes and connections. Once defined, flows can be repeatedly executed.
9+
- **Persistence, Not Volatility**: Every node's inputs, outputs, and execution state are recorded in intermediate files.
10+
- **CI-Friendly**: Long-running, fixed workflows, recoverable—suitable for CI/CD integration.
11+
12+
## Key Commands
13+
14+
| Command | Description |
15+
|---------|-------------|
16+
| `agentflow list` | List all pipelines |
17+
| `agentflow ui` | Start Web UI (port 8765) |
18+
| `agentflow apply <FlowName>` | Execute flow |
19+
| `agentflow validate <FlowName>` | Validate flow structure |
20+
| `agentflow resume <FlowName> <uuid>` | Resume from breakpoint |
21+
| `agentflow replay <FlowName> <uuid> <instanceId>` | Retry a specific node |
22+
| `agentflow run-status <FlowName> <uuid>` | View node execution status |
23+
| `agentflow extract-thinking <FlowName> <uuid>` | Extract agent thinking process |
24+
25+
## Node Types and Execution Guidelines
26+
27+
When working with AgentFlow nodes, understand the node type and apply appropriate expertise:
28+
29+
### 1. Requirement Analysis Nodes (`agentflow-node-executor-requirement`)
30+
- Focus on requirement analysis and decomposition
31+
- Understand goals and constraints first, then break down into executable steps
32+
- Output should be actionable items with clear deliverables
33+
34+
### 2. Planning Nodes (`agentflow-node-executor-planning`)
35+
- **Model**: claude-4.6-opus-high-thinking
36+
- First decompose goals into steps, clarify dependencies and order
37+
- Then execute step by step and produce documented results
38+
- Suitable for multi-step reasoning, solution design, task decomposition
39+
40+
### 3. Code Implementation Nodes (`agentflow-node-executor-code`)
41+
- **Model**: gpt-5.3-codex
42+
- Focus on code—write runnable code that conforms to project conventions
43+
- Emphasize type safety, boundary handling, readability, and maintainability
44+
- Suitable for implementing features, fixing bugs, refactoring, writing scripts/tools
45+
46+
### 4. Test/Regression Nodes (`agentflow-node-executor-test`)
47+
- Focus on testing, verification, and regression
48+
- Write or execute tests, verify results, document pass/fail status
49+
- Output should include clear test results and any failure diagnostics
50+
51+
### 5. UI/Frontend Nodes (`agentflow-node-executor-ui`)
52+
- **Model**: kimi-k2.5
53+
- Implement layout, components, styles, and interactions per design specs
54+
- Focus on visual consistency, spacing, hierarchy, responsive design, and RTL support
55+
- Suitable for component implementation, style adjustments, design walkthroughs
56+
57+
### 6. General Nodes (`agentflow-node-executor`)
58+
- General-purpose node executor
59+
- Follow node context and task body to complete work
60+
61+
## Environment Variables
62+
63+
When executing nodes, only reference these explicitly provided variables:
64+
65+
- `workspaceRoot`: Workspace root directory
66+
- `flowName`: Name of the flow
67+
- `uuid`: Unique run identifier
68+
- `instanceId`: Node instance identifier
69+
70+
## Reporting Failures
71+
72+
When a task explicitly fails, report using:
73+
74+
```bash
75+
agentflow apply -ai write-result ${workspaceRoot} ${flowName} ${uuid} ${instanceId} --json '{"status":"failed","message":"failure reason"}'
76+
```
77+
78+
## File Structure
79+
80+
```
81+
AgentFlow/
82+
├── agents/ # Agent definitions
83+
│ ├── agentflow-node-executor*.md # Node executor prompts
84+
│ └── en/ zh/ # Localized agents
85+
├── bin/ # CLI entry points
86+
├── builtin/ # Built-in pipelines and nodes
87+
├── .workspace/agentflow/ # Runtime data (per-workspace)
88+
└── ~/agentflow/ # User data directory
89+
```
90+
91+
## Workflow Tips
92+
93+
1. **For complex flows**: Use AI Composer mode in Web UI with natural language descriptions
94+
2. **Loop patterns**: Use `control_anyOne` + `control_toBool` + `control_if` for check-fix-loop patterns
95+
3. **Checkpoint recovery**: Every node state is persisted—failures can resume from the exact failure point
96+
4. **Parallel execution**: Use `--parallel` flag to execute same-round nodes concurrently
97+
98+
---
99+
100+
## Flow Editing Skills
101+
102+
### Editing Existing Node Fields (`agentflow-flow-edit-node-fields`)
103+
104+
When modifying **existing** `instances` in `flow.yaml` without changing topology:
105+
106+
**Allowed fields (whitelist):**
107+
| Field | Description |
108+
|-------|-------------|
109+
| `label` | Canvas display name |
110+
| `role` | Role category string |
111+
| `body` | Node body content (agent task description) |
112+
| `script` | **Only for `tool_nodejs`** — actual shell command to execute |
113+
| `input[].value` | Default values for input slots (don't change `type`/`name`) |
114+
| `output[].value` | Default values for output slots (don't change `type`/`name`) |
115+
116+
**Forbidden changes (blacklist):**
117+
- `definitionId` — changing type requires add-new + delete-old + rewire flow
118+
- `instanceId` — renaming requires updating all edges and ui.nodePositions
119+
- `input`/`output` array structure — no adding/removing/reordering items
120+
- `edges` — no modifications to connections
121+
- Adding/removing entire instance blocks — use `agentflow-flow-add-instances`
122+
123+
**Critical `tool_nodejs` rule:**
124+
- `script` field contains the actual command to execute
125+
- `body` is documentation only — **ignored when `script` exists**
126+
- Always write complete, executable commands in `script`, never natural language
127+
128+
### Adding New Instances (`agentflow-flow-add-instances`)
129+
130+
When adding **new nodes** to a flow:
131+
132+
**Node type selection:**
133+
| Condition | Recommended `definitionId` |
134+
|-----------|---------------------------|
135+
| Behavior fully determined by input, no AI reasoning | `tool_nodejs` + `script` |
136+
| Display prominent output to user | `tool_print` |
137+
| Requires AI understanding, judgment, content generation | `agent_subAgent` |
138+
139+
**YAML structure:**
140+
```yaml
141+
instances:
142+
<instanceId>:
143+
definitionId: <builtin or existing definition>
144+
label: ...
145+
role: ...
146+
input: [ { type, name, value }, ... ]
147+
output: [ { type, name, value }, ... ]
148+
script: <optional, tool_nodejs only>
149+
body: | ...
150+
edges:
151+
- source: <instanceId>
152+
target: <instanceId>
153+
sourceHandle: output-0
154+
targetHandle: input-0
155+
ui:
156+
nodePositions:
157+
<instanceId>:
158+
x: <number>
159+
y: <number>
160+
```
161+
162+
**Handle quick reference:**
163+
| definitionId | Common outputs | Common inputs |
164+
|--------------|----------------|---------------|
165+
| control_start | next → output-0 | — |
166+
| control_end | — | prev → input-0 |
167+
| control_if | next1 → output-0, next2 → output-1 | prev → input-0, prediction → input-1 |
168+
| control_toBool | next → output-0, prediction → output-1 | prev → input-0, value → input-1 |
169+
| control_anyOne | next → output-0 | prev1 → input-0, prev2 → input-1 |
170+
| tool_nodejs | next → output-0, result → output-1 | prev → input-0, [dynamic inputs] |
171+
172+
**Default node position:** Place new nodes starting at `x: 100, y: 300`. For linear/main-chain flows, increment `x` by **280** per node (e.g. `x: 100 + i * 280, y: 300`). For branches, offset `y` by **200** between paths. For parallel nodes, keep same `x` and offset `y` by **200**.
173+
174+
**Single responsibility principle:** Each node does one thing. Split multi-step tasks into separate nodes connected by edges.
175+
176+
### Sync Web UI After Flow Changes (`agentflow-flow-sync-ui`)
177+
178+
After writing `flow.yaml` to disk in Web UI + Composer context:
179+
180+
```bash
181+
curl -sS -X POST http://127.0.0.1:<PORT>/api/flow-editor-sync \
182+
-H 'Content-Type: application/json' \
183+
-d '{"flowId":"<flowId>","flowSource":"user"}'
184+
```
185+
186+
**`flowSource` values:**
187+
- `user` — `~/agentflow/pipelines` directory
188+
- `workspace` — `.workspace/agentflow/pipelines` in current project
189+
- `builtin` — package's `builtin/pipelines` (read-only templates)
190+
191+
---
192+
193+
## UI Design Standards: Orchestral Logic
194+
195+
Apply these design principles when working on AgentFlow Web UI:
196+
197+
**Core philosophy:** Treat data pipelines as a living score —高端 technical environment, not rigid corporate dashboard.
198+
199+
### Visual Principles
200+
201+
- **Intentional asymmetry**: Sidebars need not mirror; one side can favor density, the other whitespace
202+
- **Tonal depth over lines**: No 1px borders dividing sections; use color weight and surface layers
203+
- **Technical + organic**: Monospace rawness + large radii (`xl = 1.5rem`) + organic SVG curves
204+
205+
### Color & Surface Stack
206+
207+
| Token | Hex | Usage |
208+
|-------|-----|-------|
209+
| `surface` | `#131313` | Canvas (infinite base) |
210+
| `surface_container_low` | `#1c1b1b` | Secondary areas, sidebars |
211+
| `surface_container_high` | `#2a2a2a` | Node bodies (closer) |
212+
| `surface_container_highest` | `#353534` | Floating menus with glass |
213+
| `surface_container_lowest` | `#0e0e0e` | Sunken input backgrounds |
214+
| `on_surface` | `#e5e2e1` | Body text and icons (**never** pure white) |
215+
216+
**Functional accent colors:**
217+
- File/Stream: `secondary` `#9ecaff` (blue)
218+
- Boolean/Logic: `tertiary` `#00e475` (green)
219+
- Text/Strings: `primary_fixed` `#e8deff` (pale lavender)
220+
- Node/Flow: `primary_container` `#7c4dff` (deep purple)
221+
222+
### Typography
223+
224+
- **Space Grotesk**: Headlines, labels
225+
- **Inter**: Titles, body text
226+
- **Monospace**: Port labels, code snippets (`label-sm = 0.6875rem`)
227+
228+
### Component Specs
229+
230+
**Nodes:**
231+
- Container: `surface_container_high`, `rounded-xl` (1.5rem)
232+
- Header bar: `surface_container_highest`, `rounded-t-xl`, no divider line
233+
- Ports: Colored dots per function type; 2px `surface` gap around port
234+
235+
**Buttons:**
236+
- Primary: `primary_container` bg + `on_primary_container` text, `rounded-full`
237+
- Ghost: No bg, `primary` text, `outline_variant` @ 20% border
238+
239+
**Inputs:**
240+
- Default: `surface_container_lowest` (sunken)
241+
- Focus: `surface_bright` bg + subtle `primary` glow
242+
243+
**Connections (SVG):**
244+
- Cubic Bezier curves, 2px stroke
245+
- Gradient stroke from output port color to input port color
246+
247+
### Signature Interaction: The Pulse
248+
249+
When node is processing:
250+
- Background breathes between `surface_container_high` and `surface_variant`
251+
- ~2s cycle, `ease-in-out` sine wave
252+
- Conveys life in pipeline,替代 harsh spinners
253+
254+
### Implementation Checklist
255+
256+
- [ ] Section divisions use surface tones only, no 1px lines
257+
- [ ] Text uses `on_surface`, never `#FFFFFF`
258+
- [ ] Selection uses tint glow, not hard borders
259+
- [ ] Floating layers have blur + semi-transparent surface
260+
- [ ] Ports have 2px gap; connections are 2px gradient Bezier
261+
- [ ] Running state uses Pulse breathing, not spinning loaders

‎README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@
77
> **Orchestration system for long-running complex agent tasks.**
88
> AgentFlow uses graphs to encode dependencies and control flow, treating Cursor, OpenCode, and Claude Code (in progress) as **swappable execution backends**. Battle-tested on **large engineering efforts**—not a demo script, but a runtime that can finish, pause, and resume.
99
10+
![AgentFlow Projects](docs/projects.png)
11+
*Manage your distributed node architectures and monitoring pipelines*
12+
13+
![Pipeline Editor](docs/pipeline.png)
14+
*Visual drag-and-drop orchestration with AI-powered Composer*
15+
16+
![Running Status](docs/running.png)
17+
*Real-time execution console with checkpoint recovery*
18+
1019
## The Origin: From Pain Point to Solution
1120

1221
### That Migration Task That Broke Me
@@ -37,6 +46,9 @@ AgentFlow doesn't aim to replace Cursor or OpenCode, but **builds upon them**:
3746
- **Checkpoint Resumption**: Every node state persisted, precise problem node location on failure, single-node retry or full recovery, no need to start from scratch
3847
- **CI/CD Ready**: Fixed workflows, repeatable execution, long-running support, naturally suited for continuous integration scenarios
3948

49+
![Pipeline Architecture](docs/pipeline.png)
50+
*A complex module migration workflow with loops and conditional branches*
51+
4052
The hard part of complex work is rarely "model quality alone"—it is **state, boundaries, and cadence**: who depends on whom, where humans must sign off, and which checkpoint to restart from after failure. AgentFlow models workflows as **nodes + directed edges**: a scheduler advances a **ready set** from dependency closure; each node binds an agent capability to a backend. Run directories persist artifacts and per-node status, yielding **observability** and **recoverability** (pause / resume / replay). Orchestration stays decoupled from your codebase: swap tools; keep the graph and execution semantics.
4153

4254
## Common Scenarios
@@ -54,6 +66,9 @@ Move testing from "when someone remembers" to a **slow-burn loop**: schedule or
5466

5567
Detailed tutorials available in Wiki docs:
5668

69+
**🚀 Quickstart: [PR Workflow Automation](docs/wiki/quickstart-pr-workflow.en.md)**
70+
Real story: How I automated code review → PR creation → team notification with 100% reliability. Learn how AgentFlow solves the "AI sometimes forgets steps" problem.
71+
5772
**1. [Module Migration Workflow](docs/wiki/module-migration-workflow.en.md)**
5873
Migrate code from main module to submodule: scan → analyze dependencies → migrate → compile → loop fix. Demonstrates how to implement "check-fix-check" cyclic pattern with `control_anyOne` + `control_if`, supporting checkpoint resumption and single-node retry.
5974

@@ -64,6 +79,45 @@ One-shot implementation of complex Figma designs: parse design → extract compo
6479

6580
Shortest path: install → first pipeline → validate → run → diagnose and resume.
6681

82+
### Prerequisites
83+
84+
Before installing AgentFlow, ensure you have one of the following Coding Agent CLI tools:
85+
86+
**Option 1: Cursor CLI (Recommended)**
87+
```bash
88+
# Install Cursor CLI
89+
# Download from https://cursor.com or install via:
90+
brew install --cask cursor # macOS
91+
92+
# Verify installation
93+
agent --version
94+
```
95+
96+
**Option 2: OpenCode CLI**
97+
```bash
98+
# Install OpenCode CLI
99+
npm install -g opencode
100+
101+
# Verify installation
102+
opencode --version
103+
```
104+
105+
**Configure settings (Optional)**
106+
107+
AgentFlow uses environment variables for CLI configuration:
108+
109+
```bash
110+
# Set default CLI command (default: agent)
111+
export CURSOR_AGENT_CMD=agent
112+
113+
# Set default model
114+
export CURSOR_AGENT_MODEL=claude-sonnet
115+
116+
# Or add to your ~/.zshrc or ~/.bashrc:
117+
echo 'export CURSOR_AGENT_CMD=agent' >> ~/.zshrc
118+
echo 'export CURSOR_AGENT_MODEL=claude-sonnet' >> ~/.zshrc
119+
```
120+
67121
### 1. Installation
68122

69123
Requirements: Node >= 18, Cursor CLI installed (`agent` command available)

0 commit comments

Comments
 (0)