@hmj-ai/cflow 1.1.0

package/DESIGN.md

@@ -0,0 +1,241 @@
+---
+name: CFlow Quiet Light Workbench
+description: A restrained light workbench that lets non-technical staff read, adjust, check, and publish agent Flows in plain language.
+colors:
+  paper: '#f6f7f9'
+  paper-deep: '#eef0f4'
+  surface: '#ffffff'
+  panel: '#fbfbfc'
+  inset: '#f2f4f7'
+  white: '#ffffff'
+  text: '#1d2126'
+  muted: '#5b636d'
+  faint: '#8a919b'
+  border: '#e5e8ec'
+  border-strong: '#d2d7de'
+  accent: '#35569e'
+  accent-deep: '#2b4681'
+  accent-soft: '#eef1f8'
+  green: '#16794e'
+  green-soft: '#e8f3ed'
+  amber: '#8f6314'
+  amber-soft: '#fbf2df'
+  red: '#b0392d'
+  red-soft: '#fbecea'
+typography:
+  display:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif'
+    fontSize: 'clamp(22px, 2.6vw, 30px)'
+    fontWeight: 600
+    lineHeight: 1.25
+    letterSpacing: '-0.012em'
+  headline:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif'
+    fontSize: '17px'
+    fontWeight: 600
+    lineHeight: 1.5
+    letterSpacing: '-0.008em'
+  title:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif'
+    fontSize: '14px'
+    fontWeight: 600
+    lineHeight: 1.5
+    letterSpacing: 'normal'
+  body:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif'
+    fontSize: '14px'
+    fontWeight: 400
+    lineHeight: 1.6
+    letterSpacing: 'normal'
+  label:
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans CJK SC", "PingFang SC", "Microsoft YaHei", system-ui, sans-serif'
+    fontSize: '11px'
+    fontWeight: 600
+    lineHeight: 1.5
+    letterSpacing: '0.02em'
+  mono:
+    fontFamily: '"SFMono-Regular", Consolas, "Liberation Mono", monospace'
+    fontSize: '11px'
+    fontWeight: 400
+rounded:
+  indicator: '50%'
+  compact: '5px'
+  control: '7px'
+  standard: '8px'
+  overlay: '9px'
+  card: '10px'
+  node: '11px'
+  field-group: '12px'
+  emblem: '14px'
+spacing:
+  hairline: '2px'
+  micro: '5px'
+  compact: '8px'
+  control: '10px'
+  standard: '12px'
+  section: '18px'
+  panel: '20px'
+  spacious: '24px'
+components:
+  button-standard:
+    backgroundColor: '{colors.surface}'
+    textColor: '{colors.text}'
+    borderColor: '{colors.border-strong}'
+    typography: '{typography.label}'
+    rounded: '{rounded.control}'
+    padding: '0 11px'
+    height: '34px'
+  button-signal:
+    backgroundColor: '{colors.accent}'
+    textColor: '{colors.white}'
+    typography: '{typography.label}'
+    rounded: '{rounded.control}'
+    padding: '0 11px'
+    height: '34px'
+  button-publish:
+    backgroundColor: '{colors.surface}'
+    textColor: '{colors.green}'
+    borderColor: '{colors.border-strong}'
+    typography: '{typography.label}'
+    rounded: '{rounded.control}'
+    padding: '0 11px'
+    height: '34px'
+  input:
+    backgroundColor: '{colors.surface}'
+    textColor: '{colors.text}'
+    borderColor: '{colors.border-strong}'
+    typography: '{typography.body}'
+    rounded: '{rounded.control}'
+    padding: '0 10px'
+    height: '34px'
+  flow-node:
+    backgroundColor: '{colors.surface}'
+    textColor: '{colors.text}'
+    borderColor: '{colors.border}'
+    rounded: '{rounded.node}'
+    width: '190px'
+  mark:
+    backgroundColor: '{colors.accent-soft}'
+    textColor: '{colors.accent}'
+    rounded: '{rounded.overlay}'
+---
+
+# Design System: CFlow Quiet Light Workbench
+
+## Overview
+
+**Creative North Star: "安静的办公桌面"**
+
+CFlow is used by staff who do not write code. The interface therefore behaves like a
+well-organised desk rather than an operator console: a near-white ground, hairline
+rules, plain-language labels, and one quiet accent that only ever marks the single
+next step. Nothing blinks, nothing shouts, and no screen asks the reader to
+understand a protocol, a hash, or a DSL in order to do their job.
+
+The system is deliberately monochrome-dominant. Colour carries meaning, never
+decoration: the slate-blue accent means "this is the action to take now", green means
+"cleared", amber means "waiting on a person", red means "stopped". Everything else is
+neutral. Technical facts are never deleted — they are demoted behind an explicit
+disclosure so the one colleague who needs to reconcile a run can still find them.
+
+**Key Characteristics:**
+
+- A top bar for flow management, then three panels — detail, canvas, assistant — plus a drawer under the canvas.
+- Exactly one filled button per screen: whatever the user should do next.
+- Status is a small dot plus a word, never a large colour fill and never colour alone.
+- Business language on the surface; identifiers, versions, and hashes behind 「技术细节」.
+- Desktop only. Side panels collapse to a 50px rail; there is no mobile drawer.
+
+## Colors
+
+The palette is neutral-first. Six greys carry the entire structure; the accent and
+three status hues are used at small scale only.
+
+| Token                  | Value                 | Use                                                       |
+| ---------------------- | --------------------- | --------------------------------------------------------- |
+| `paper`                | `#f6f7f9`             | App ground behind all panels                              |
+| `panel`                | `#fbfbfc`             | Flow list rail                                            |
+| `surface`              | `#ffffff`             | Cards, fields, node bodies, overlays                      |
+| `inset`                | `#f2f4f7`             | Search field, hover rows, count chips                     |
+| `border`               | `#e5e8ec`             | Default hairline                                          |
+| `border-strong`        | `#d2d7de`             | Control outlines, focused separation                      |
+| `text`                 | `#1d2126`             | Primary copy                                              |
+| `muted`                | `#5b636d`             | Secondary copy, helper text                               |
+| `faint`                | `#8a919b`             | Meta, timestamps, placeholder                             |
+| `accent`               | `#35569e`             | The single next action, active tab, focus ring, selection |
+| `accent-soft`          | `#eef1f8`             | Selected row, mark blocks, quiet chips                    |
+| `green` / `green-soft` | `#16794e` / `#e8f3ed` | Cleared, published, healthy                               |
+| `amber` / `amber-soft` | `#8f6314` / `#fbf2df` | Draft, waiting for a person                               |
+| `red` / `red-soft`     | `#b0392d` / `#fbecea` | Failed, destructive, blocked                              |
+
+Contrast rule: any coloured text sits on `surface`, `paper`, or its own `-soft`
+partner — never white text on a light token. All status hues meet 4.5:1 on white.
+
+## Typography
+
+One system stack, weights capped at 600. The old desk used 680–800 weights and
+−0.035em tracking; both read as "engineering tool" and are gone.
+
+- Display 22–30px/600 for view titles only.
+- Headline 17px/600 for section headers.
+- Title 14px/600 for card and row names.
+- Body 14px/400 at 1.6 line-height for anything the user must actually read.
+- Label 11px/600, +0.02em, uppercase only for group headers.
+- Mono 11px reserved for filesystem paths and disclosed technical values.
+
+## Layout
+
+- Rows: `52px` top bar, an auto notice row, then the workbench.
+- Workbench grid: `300px | minmax(560px, 1fr) | 340px`; either side collapses to `50px`.
+- With no flow, the workbench collapses to a single full-width column.
+- Minimum viewport 1280px. Desktop only, by product decision.
+- The canvas toolbar holds step-adding buttons on the left and the action ladder (检查/测试/运行/发布) on the right.
+- The centre column is the goal composer until a flow exists, then the canvas.
+- The drawer under the canvas holds 日志 and 检查. It never opens by itself.
+
+## Elevation & Depth
+
+Effectively flat. Separation comes from hairlines and the ground/surface step.
+A single soft shadow (`0 8px 24px rgba(24,32,46,.1)`) is permitted for overlays
+and the settings sheet. Node cards, buttons, and panels cast no shadow.
+
+## Shapes
+
+7px for controls, 8–10px for cards and overlays, 11px for flow nodes, 50% for
+status dots. No pills except the canvas 「开始」 marker.
+
+## Components
+
+- **Button** — outline by default. `.signal` adds the one accent fill on screen.
+  `.publish` is outline with green text and only fills once a test has passed.
+  `.danger` is red text on white; it fills only inside a confirmed destructive flow.
+- **Flow node** — kind label, sequence number, human name, one line of plain
+  description, an optional quiet config chip, and a status dot with a word. The node
+  never shows an internal id as its title.
+- **Status dot** — 7–8px, paired with a text label, in green/amber/red/neutral.
+- **Mark block** — `accent-soft` ground with `accent` glyph, for view emblems.
+- **Technical disclosure** — a closed `<details>` holding ids, versions, hashes, and
+  raw JSON. Present on the check panel, the run log, and the detail panel.
+- **Bottom drawer** — tab strip plus close button, sized `min(38vh, 320px)`, a flex
+  sibling under the canvas so it resizes the canvas instead of covering its controls.
+- **Flow switcher** — one flat list of drafts and published versions with a status
+  tag per row, search, per-row delete, and 新建流程 at the foot.
+
+## Do's and Don'ts
+
+**Do**
+
+- Name the next step and fill exactly that one button.
+- Write every label as a sentence a colleague in HR or finance would understand.
+- Translate error codes into what to change and where.
+- Keep hidden system folders out of the folder picker by default.
+- Label a branch edge with the routing rule the author wrote, not the case id.
+
+**Don't**
+
+- Don't put white text on a light token; check contrast when retinting.
+- Don't surface `cfId`, `planHash`, `programHash`, `policyRef`, or "DSL/ACP/manifest"
+  on a primary surface — disclose them instead.
+- Don't use two filled buttons on one screen; the fill is computed by `nextSignalAction`.
+- Don't encode state in colour alone, and don't animate to attract attention.
+- Don't add a mobile or touch layout; that is out of product scope.

package/README.md

@@ -0,0 +1,111 @@
+# CFlow
+
+CFlow 是一个以 **Flow** 为核心的本机多 Agent 编排工作台。用户可以用自然语言描述目标，由系统结合 CF 能力库生成可审阅的流程草稿，也可以直接在 DAG 画布中组合、检查、测试、发布和运行流程。
+
+## 当前设计
+
+CFlow 不以 Project 为一级对象。每个 Flow 固定一个本机工作目录，代码仓库、文件集和外部资源都作为 Flow 的运行时上下文或 Resource Profile 使用。
+
+完整工作流为：
+
+```text
+选择工作目录 → 描述目标/附加 skill → 生成草稿 → 画布编辑
+→ 检查 → 测试 → 发布不可变版本 → 运行 → 查看日志或继续询问助手
+```
+
+系统采用两级自然语言编程模型：
+
+```text
+CFDraft（自然语言函数源）
+  → cf-compiler → CFProgram
+  → 测试并发布 CFVersion
+
+FlowDraft（组合已发布 CFVersion）
+  → flow-compiler → FlowPlan DAG
+  → 测试并发布 FlowVersion
+  → Flow Engine 调度 CF Runtime
+  → CF Runtime 调用已固定的 Agent Runtime
+```
+
+CFlow 的关键约束：
+
+- Flow 是可审阅、可版本化的 DAG；CF 是一个有边界的 Agent 能力，内部不再维护第二套控制流。
+- Agent 可以提出或修订草稿，但不能改变已发布图、审批结果、权限或运行事实。
+- 检查、测试、发布、运行是独立阶段；测试使用临时编译快照，发布会固定 CF、Runtime Profile、资源和工作目录。
+- 数据沿连线传递完整 Flow 输入与已激活的上游输出，不维护字段级 Binding。
+- Run Ledger、Job Lease 与 SSE 事件记录执行事实，支持条件分支、共享汇合、审批、重试和取消。
+
+工作台仅面向最小宽度 1280px 的桌面浏览器。顶栏负责流程切换和设置；主区域为左侧详情、中间画布、右侧助手，画布下方提供检查和日志抽屉。左右栏可以收起为窄轨，不提供移动端或触控布局。界面优先使用业务语言，内部 ID、版本和 hash 收在“技术细节”中；同一屏只突出当前下一步操作。
+
+视觉令牌、组件规则和交互原则统一维护在 [`DESIGN.md`](./DESIGN.md)。
+
+## 安装与运行
+
+需要 Node.js 22 或更高版本。
+
+直接从 npm 启动：
+
+```bash
+npx @hmj-ai/cflow
+```
+
+或全局安装：
+
+```bash
+npm install -g @hmj-ai/cflow
+cflow
+```
+
+从源码运行：
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+打开 `http://127.0.0.1:3000`。默认数据库写入 `data/cf.sqlite`，可通过 `CF_DB=/path/to/file.sqlite` 指定其他位置；开发模式使用 `npm run dev`。
+
+服务默认只监听 `127.0.0.1`，因为 Runtime 设置可以启动本机受控进程。只有在已经配置外部认证与网络访问控制时，才应通过显式 `HOST` 改为其他监听地址。
+
+## Runtime 与设置
+
+工作台内置 Codex 与 Claude Code，并通过声明式 manifest 接入 Grok Build、Pi 等本机 Agent。普通用户只需选择默认 Agent 和工作目录：
+
+- 页面加载与设置页“重新识别”会合并 PATH ACP、npm 包、用户 manifest 和项目 manifest；来源与无效 manifest 警告会明确展示。
+- Codex 与 Claude Code 通过内置 ACP Adapter 执行；Grok Build 与 Pi 是普通项目 manifest。所有命令均使用 argv 数组启动，不拼接 shell 命令字符串。
+- ACP 必须完成真实 `initialize` 握手才标记为可用；CLI 必须通过无副作用的版本探测。认证状态不会用可能计费的模型请求猜测。
+- Runtime 配置每次保存都会生成不可变 Profile 版本；发布 Flow 时会 pin 精确 Profile 版本，Run Ledger 记录实际执行版本。
+- 设置页只暴露默认 Agent、本地工作目录和测试最长等待时间；资源绑定按需放在折叠的高级区域。
+- Runtime 必须返回符合 CF output contract 的 JSON，否则 Flow fail closed。
+- Flow/CF 草稿会保存到 SQLite；Resource Profile 可在设置中创建、编辑与删除。
+
+非内置 Agent 可以通过 JSON manifest 接入。项目级文件放在 `<workspace>/.cflow/agents.d/*.json`，用户级文件放在 `~/.config/cflow/agents.d/*.json`；项目配置优先级更高。最小示例：
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "example-agent",
+  "name": "Example Agent",
+  "backend": "cli",
+  "command": "example-agent",
+  "versionArgs": ["--version"],
+  "promptTransport": "stdin",
+  "outputMode": "json"
+}
+```
+
+`backend` 支持 `acp` 和 `cli`。还可以通过 npm 包的 `cflowAgent` 字段声明 manifest；无效配置会被跳过，并在设置页显示原因。
+
+安全边界按事实展示：Process Runtime 只承诺独立子进程、工作区根目录内的限定 cwd、清理环境、超时/取消与参数化启动；除非具体 adapter 明确提供，否则不声称网络隔离或主机级文件系统沙箱。当前 Process Adapter 收集最终输出，不把底层 CLI 的流式片段、tool events 或 token usage 伪装成产品已暴露能力。密钥值不写入产品数据库，只按配置的变量名从服务端环境继承。
+
+## 开发与验证
+
+```bash
+pnpm test
+pnpm run typecheck:web
+pnpm run format:check
+pnpm run build
+```
+
+技术栈为 TypeScript、Fastify、React、XYFlow、SQLite 和 Vite。生产构建输出到 `dist/`，npm 包只包含运行产物、README 和唯一的设计文档 `DESIGN.md`。