宜博 / lemongraph

05-实施约束与依赖.md 16.8 KB

05-实施约束与依赖

5.1 现有资产复用清单（来自本地 Hermes profile 调研，架构文档第 9 节）

Org Agent 复用来源 复用内容 迁移动作
Planner ~/.hermes/profiles/planning/ SOUL.md（16 条根本原则）；planning-requirement-expansion、project-brd-planning、project-prd-planning、project-sdd-planning（本 SDD 采用的方法论本身）、project-unit-decomposition、review-blocker-verification 等 skill SOUL.md 正文迁移到目标项目 .claude/agents/planner.md（frontmatter 配 skills:/memory: project/tools:/model:，见架构文档 7.2 节），skill 迁移到 graphlemon/skills/* 供 skills: 字段引用
Coder ~/.hermes/profiles/code/ SOUL.md（认领→实现→测单→证据回写）；code-task-development、code-agent-engineering、debugging-toolkit、software-planning-execution 迁移到 .claude/agents/coder.md + graphlemon/skills/*，需要改造：原流程强绑定飞书 Base 认领机制，改为消费 task 表 + c_org_node_trigger
Validator ~/.hermes/profiles/qa/ SOUL.md + AGENTS.md（三态判定、双向可追溯矩阵、工作区权限契约）；qa-task-validation、unattended-agent-operations 迁移到 .claude/agents/validator.md（AGENTS.md 的工作区权限契约折入 tools/disallowedTools frontmatter），双向可追溯矩阵直接对应 04-P p_validator_root_cause_trace 的血缘追溯步骤

不复用：三个 profile 的 memories/MEMORY.md/USER.md（内容重叠、未按角色隔离）；.archive/、migration/、openclaw-imports/ 下的通用助理技能（apple、creative、feishu-lark 等）。

5.2 飞书 Base 替换计划（架构文档 12.1 节已确认）

  • 不做历史数据自动迁移，MVP 从空任务队列开始运行
  • 原 lark-cli --as user 的认领/回写语义，改由 c_org_node_trigger + task.status 状态机承接
  • 原飞书 Base 的人工可视化能力，由本 SDD 02-V 的 v_task_board/v_task_detail/v_graph_visualizer 承接

5.3 执行后端范围（架构文档 7.2 节决策，2026-07-29，取代此前"双后端不对等"框架）

  • MVP 阶段只实现并使用 Claude Code ACP 一种执行后端，不考虑 Hermes CLI 作为执行后端。此前"Org Graph 层两后端一致、Work Graph 层两后端不对等"的处理方案已作废——不存在第二个后端。
  • Org Graph 层：c_org_node_trigger 底层是 claude --agent <planner|coder|validator> -p "..."，Org Agent 身份由目标项目 .claude/agents/*.md 承载（见 5.1 节迁移动作）
  • Work Graph 层：c_work_graph_execute 跑完整的 fan-out/fan-in/loop 能力（见 03-C 3.5 节），MVP 验收标准是这一条能跑通即可，不再需要"至少验证一种后端"这类留有余地的表述
  • v_graph_visualizer 不再需要"简化模式"展示逻辑（02-V 2.7 节保持单一展示模式）
  • Executor Interface 的抽象层设计仍保留为未来扩展点，但不是当前实现范围

5.4 依赖的外部能力（对应 00 节 A-1，已通过 spike 实测确认）

  • Claude Code 动态工作流的 agent()/parallel()/pipeline() 原语已实测确认可通过 claude -p（非交互式）编程方式调用，方案 A 成立（spikes/a1-dynamic-workflows/，真实账号验证，2026-07-29，成本 $0.46）：
    • claude -p 'Run /<workflow> with args {...}' --output-format json --json-schema <schema> < /dev/null 无交互提示、无挂起、40s 内完成，structured_output 精确匹配预期输出，permission_denials 为空
    • 发现的约束：不能加 --bare。--bare 会跳过登录态/凭据发现（报 Not logged in，与是否存在 workflow 无关），必须用不带 --bare 的完整冷启动调用，代价是启动稍慢，但可靠性优先
    • 具体实现契约（写入 workflow 脚本、子进程调用、解析 structured_output、回填预算用量）已落地到 03-C 3.5 节
  • 原风险已解除，不再需要在实施第一周单独排期做技术验证；架构文档 10.1 节的方案 B（完全自研 Graph Engine）作为长期备选保留，暂不启用

5.4.1.1 --agent 与 --json-schema 不能同时生效（发现，2026-07-31，U-011）

  • 实测确认：claude --agent <name> -p ... --json-schema <schema> 时，--json-schema 被静默忽略——返回的 JSON payload 里 structured_output 字段整个不存在，模型改成把结构化内容以自由文本 + ```json 围栏代码块的形式塞进 result 字段里；但 --agent 本身工作正常（人设确实生效，回复里引用了迁移后 SOUL.md 的具体条目编号）
  • 这条约束和 5.4 节 A-1 spike 的场景不同：A-1 验证的是不带 --agent 的动态工作流调用（claude -p 'Run /<workflow>...'），--json-schema 在那种调用形式下是生效的（structured_output 精确匹配）；只有同时传 --agent 和 --json-schema 时才会出现这个静默失效
  • 应对方式：需要"某个 Org Agent 身份 + 结构化输出"同时成立时（如 c_work_graph_plan，见 03-C 3.4 节/U-011），不要依赖 --json-schema/structured_output，改为在 prompt 里明确要求模型把结果包在单个 ```json 围栏代码块里，再从 result 字段用正则提取解析，对"整段就是 JSON"和"围栏代码块"两种情况都做兜底解析（参考实现：src/work_graph_plan.py 的 _extract_graph_manifest）
  • 未在 Anthropic 官方文档里找到这条限制的说明，是靠实测发现的，不排除后续版本行为会变——如果这里升级过 Claude Code 版本，值得重新验证一次

5.4.1.2 subagent frontmatter 的 disallowedTools 不支持按子命令限定（发现，2026-07-31，U-014 真实闭环跑出来的）

  • 实测确认：.claude/agents/<name>.md frontmatter 里的 disallowedTools，只要出现任意 Bash(某子命令:*) 这种按子命令限定的写法（如 Bash(git commit:*)），Bash 工具会被整体禁用，不是只挡住那一条子命令——即使同一份 frontmatter 的 tools: 字段里明确写了 Bash。用一个只有 tools:[Read,Bash]、disallowedTools:[Edit,Write]（不含任何 Bash(...)）的最小测试 agent 验证过 Bash 能正常跑；一旦给 disallowedTools 加一条 Bash(git commit:*)，同一个 agent 立刻连 echo 都跑不了
  • claude --help 里 --disallowedTools/--allowedTools CLI 参数本身明确支持这种按子命令限定的写法（帮助文本示例就是 Bash(git *) Edit），但 subagent frontmatter 里的同名字段不支持同一种语法——是两个不同的解析路径，行为不一致，官方文档没有说明这个差异
  • 实际后果：U-004 迁移 Validator 人设时，原本想用 disallowedTools: [Edit, Write, Bash(git commit:*), Bash(git push:*), Bash(git reset:*), Bash(git clean:*)] 把"不准改代码"和"不准动 git 历史"都在工具层锁死，结果是 Validator 真实调用时完全没有 Bash 权限，无法运行任何测试——这个问题一直存在到 U-019 之后才通过跑 U-014 完整真实闭环时暴露出来（Validator 给出 INCONCLUSIVE 判定时明确说"没有 Bash 工具"）。已订正为 disallowedTools: [Edit, Write]（不再限定 Bash 子命令），"不准动 git 历史"这条约束现在只靠 AGENTS.md 里的文字指令，不是工具层强制——一个跑不了任何测试的 Validator 比一个理论上可能跑 git commit 的 Validator 风险大得多，两权相害取其轻
  • 同 §5.4.1.1：这条限制没在官方文档里找到说明，是实测发现的，不排除后续版本行为会变——升级 Claude Code 版本后值得重新验证

5.4.2 Claude Code plan 额度等待重试参数（架构文档 7.5 节决策，2026-07-29）

  • 退避轮询间隔（5→10→20→30 分钟，上限 30 分钟）、超时兜底阈值（session 8 小时、weekly 9 天）是 MVP 阶段的硬编码默认值，不在管理后台开放用户配置，和 log_retention_config 的"保留天数可配、清理频率不可配"是同一个 MVP 简化原则
  • 这组参数的合理性依赖 Claude Code 官方文档给出的窗口周期（5 小时滚动 / 7 天）本身不变；若未来 Claude Code 调整了额度窗口周期，需要同步调整这里的超时阈值，不是一次性写死可以忽略的常量

5.3.1 c_work_graph_execute 权限模式决策（03-C 3.5 节，2026-07-29）

  • 选定 --permission-mode auto，而非 --dangerously-skip-permissions/bypassPermissions：后者官方文档明确要求只能在隔离容器/VM+无网络访问环境下使用；graphlemon 目前的节点隔离手段（git worktree）是同机目录级隔离，达不到这个前提，用 bypassPermissions 会暴露 prompt injection 风险
  • 约束 1（模型选型）：auto mode 要求会话模型为 Claude Sonnet 5 / Opus 4.7+ / Fable 5（Anthropic API 上），架构文档 10 节"按节点分层选模型"给 Coder/Validator 节点选便宜模型时不能选到这个集合以外
  • 约束 2（失败模式）：-p 非交互模式下，分类器连续拦截 3 次或累计 20 次会导致会话直接中止（无人可确认），对应 c_work_graph_execute 新增 CLASSIFIER_BLOCKED 错误码，路由到 blocked_pending_human（04-P 已补充）
  • 待办（非 MVP 阻塞项，值得后续排期）：auto mode 支持通过"受信任基础设施"配置（autoMode.environment）减少误拦截，architecture.md 目前未定义 graphlemon 自己的可信基础设施清单（例如目标项目的 git remote、允许访问的包registry等），MVP 阶段先接受更高的误拦截率、靠人工在 v_task_detail 复核放行，后续可评估是否要把这份配置纳入 org_graph_definition 或新增专门的设置页

5.4.1 控制台载体形态的实施约束（架构文档 13.1 节决策 5，已确认）

  • 控制台是本地 Web 应用，后端是本机常驻进程（同时也承担 Graph Engine 的调度职责），前端是普通网页，两者本地通信（如 localhost 端口）
  • c_pick_folder 依赖后端所在操作系统的原生对话框能力：macOS 用 osascript，Windows/Linux 需要各自的原生方案（如 PowerShell 脚本 / zenity/kdialog），实施时需要按目标操作系统分别验证，不是一套代码天然跨平台
  • 若后端运行在无图形界面的环境（纯服务器/容器），c_pick_folder 会返回 DIALOG_UNAVAILABLE，v_project_setup 需要有手动路径输入的兜底交互（MVP 阶段可以直接做成兜底默认项，不必等图形环境不可用时才现场适配）

5.5 上线顺序与兼容性

  1. 先落地 01-M 的数据模型（task/artifact/skill 等核心表）+ Git 仓库目录结构（架构文档 7.3 节）
  2. 再落地 Org Graph 层接口（3.1-3.3, 3.11-3.13）+ p_org_task_lifecycle 状态机，此时可先用手工调用验证 Planner/Coder/Validator 三个 Org Agent 分别可被触发
  3. 最后落地 Work Graph 层（3.4-3.6）与 Claude Code 动态工作流的集成；A-1 已通过 spike 实测确认（见 5.4 节），可按 03-C 3.5 节的已验证实现契约直接开发，无需再单独排期做技术验证

5.6 迁移与回滚约束

  • org_graph_definition 的变更（Org Graph 结构本身）走人工 PR 评审流程，不允许系统自主提交
  • skill 的自主迭代（c_skill_update）允许系统自主提交，但必须可通过 c_skill_rollback 一键回滚到迭代前版本
  • MVP 阶段数据库 schema 变更暂不考虑蓝绿发布/双写迁移（单用户本地运行，允许停机迁移）——例外：graphlemon 平台自身的 self-target 场景不适用这条"允许停机迁移"的简化假设，见 5.8 节

5.7 graphlemon 自身实现技术栈（决策，2026-07-30）

  • graphlemon 自身的后端（HTTP API + WebSocket/SSE server + Graph Engine 调度）与 PH5 的 Deploy Supervisor 进程，统一采用纯 stdlib Python 实现，不依赖任何第三方包（不用 Flask/FastAPI/Express/Node.js），对齐前身项目 graphloop 的既有约定（graphloop/CLAUDE.md原话："Everything is stdlib: argparse, sqlite3, http.server, subprocess, threading, unittest, etc."）
  • 前端是本地 Web 应用（浏览器页面），后端用 http.server/socketserver 等 stdlib 原生能力提供 HTTP API；WebSocket 若 stdlib 支持不足，实施时（U-007）需要验证并可退化为 SSE/长轮询，但仍在 stdlib 范围内解决，不引入第三方包；前端不引入 npm/构建步骤，可以是原生 HTML/CSS/JS 或参考 graphloop graph.html/project.html 的单文件 no-build 页面模式
  • 例外：这条约束只针对 graphlemon 平台自身的实现语言，不代表 graphlemon 生成/审查的目标项目代码也必须是 Python——目标项目用什么语言由目标项目自己的技术栈决定
  • 影响：development-plan.md 的 U-007（本地后端骨架）、U-008（前端骨架）、U-036（Deploy Supervisor 骨架）的 Done 标准隐含"纯 stdlib"这条约束
  • 源码目录约定（2026-07-30 补充，2026-07-31 订正）：graphlemon 平台自身的后端源码（U-001 的 schema 实现、U-007 起的 HTTP/WebSocket 后端）落在 graphlemon 仓库根目录的 src/。这与目标项目仓库自己已有的 src/ 是两个完全不同的目录，分属两个物理仓库（见架构文档 §13.1"目标项目是独立代码空间"决策）——PH5 self-target 场景下二者会同时存在于同一台机器上，实现时不要混淆，必要时以绝对路径而非相对路径区分。订正：目标项目的 src/ 不是 U-002 生成的——U-002 只在目标项目里创建 .graphlemon/ 子目录（架构文档 §13.2），目标项目自己的 src/ 是其原有源码目录，graphlemon 不创建也不规定其结构；development-plan.md 此前 U-002 那行误引用了架构文档 §7.3 的旧目录树，已于 2026-07-31 订正（§7.3 是"graphlemon 只服务自己开发自己"阶段的旧设计，已被 §13 取代，§7.3 里的 .claude/agents/、skills/、顶层 runs/ 实际是 graphlemon 平台自己仓库的资产，属于 U-003 范围）

5.8 self-target 场景治理规则（self-development-feasibility.md 缺口 1/3，2026-07-30 回填）

  • worktree 无条件强制：target_folder_path == graphlemon 平台自身安装路径 时，无论并行还是串行，Coder/Validator 一律强制使用 git_worktree_ref，不适用 03-C 3.6 节"仅并行写代码节点才强制申请 worktree"的一般规则——这是该规则的 self-target 特例
  • core_engine 分类路由：bug_record.root_cause_category 新增枚举值 core_engine，覆盖 .claude/agents/*.md 身份文件变更、Graph Engine 调度器/执行器抽象层核心逻辑变更、01-M 自身数据库 schema 变更三类场景。命中 core_engine 时，c_org_loop_route（03-C）路由到 PH5 的 p_deploy_supervisor_blue_green 流程（04-P），而不是常规的 fast_lane/full_replan
  • 不要求提交前人工评审：core_engine 改动不强制在合并主分支前经过人工评审（此前"比照 org_graph_definition 强制人工 PR 评审"的提案已被用户明确否决），改为合并后由 Deploy Supervisor 持续监控运行时行为、检测异常时自动回滚（见 04-P p_deploy_supervisor_blue_green、docs/supervisor-auto-rollback-design.md）。5.6 节"允许停机迁移"的简化假设不适用于这类 self-target 场景——self-target 的 schema 变更同样走蓝绿部署+监控流程，不是简单停机迁移

5.9 Deploy Supervisor MVP 固定参数（docs/supervisor-auto-rollback-design.md §9，2026-07-30 回填）

参数 草案值 说明
HEALTH_CHECK_STARTUP_TIMEOUT 30s Candidate 进程从拉起到能响应探活
HEALTH_CHECK_HTTP_TIMEOUT 10s 单次 /api/health 请求
HEALTH_CHECK_CANARY_TIMEOUT 120s 一次最小 canary 任务从提交到出结果
MONITOR_SAMPLE_INTERVAL 5min process/http 采样间隔
CANARY_INTERVAL 1h 监控期 canary 任务运行间隔
MAX_CRASH_COUNT / CRASH_WINDOW 2 次 / 10min 判定进程反复崩溃
MAX_CONSECUTIVE_HTTP_FAIL 3 次 判定健康端点持续不可用
VALIDATOR_RATE_DEVIATION_THRESHOLD ±30 个百分点 判定 Validator 行为异常（validator_approval_rate 信号阈值）
MONITORING_WINDOW_HOURS 24h 监控窗口时长上限
MONITORING_MIN_TASK_COUNT 10 个真实任务 监控窗口任务数上限，先到者结束

与 5.4.2 节额度等待参数的差异：5.4.2 节的退避/超时参数依据是 Anthropic 平台文档定义的外部事实（5 小时/7 天窗口周期），可以合理标注为"MVP-fixed"；本节这组阈值是纯粹的工程经验草案，没有类似的外部权威来源，标注为"可调，需在真实跑通几轮自我修改后实测校准"，不建议实现时直接当成不可变常量硬编码进测试断言。