mirror of
https://github.com/shareAI-lab/analysis_claude_code.git
synced 2026-09-22 13:23:37 +08:00
Refine course progression and runtime safety
This commit is contained in:
Haoran
@@ -6,7 +6,7 @@ s01 → ... → s15 → [s16](../s16_mcp_plugin/) → `s17` → [s18](../s18_wor
|
||||
|
||||
> *"机制很多，循环一个"* — 工具、权限、记忆、任务、团队、插件都挂在同一个 while True 上。
|
||||
>
|
||||
> **Harness 层**: 集成 — 把 s01-s16 的机制放回同一个可运行系统。
|
||||
> **Harness 层**: 集成 — 把本章示例实际使用的机制放进同一个可运行系统。
|
||||
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ s01 → ... → s15 → [s16](../s16_mcp_plugin/) → `s17` → [s18](../s18_wor
|
||||
- 任务绑定的 worktree
|
||||
- MCP 外部工具接入
|
||||
|
||||
本章的难点在于看清楚每项功能挂在循环的哪个位置。S17 是集成检查点：先把此前组件归位，再由 s18-s19 在外层加入编排与目标闭环。
|
||||
本章的难点在于看清楚每项功能挂在循环的哪个位置。S17 是集成检查点，把这个可运行示例保留的机制接入同一个 Harness。S18 在它之上加入 workflow 编排；s19 则用更小的循环单独讲目标收口。
|
||||
|
||||
---
|
||||
|
||||
@@ -79,7 +79,7 @@ S17 不再引入新机制，而是把前面各章的组件集成到同一个 har
|
||||
|
||||
### 工具与分发
|
||||
|
||||
内置工具池包含 25 个工具：
|
||||
内置工具池包含 24 个工具：
|
||||
|
||||
```text
|
||||
bash, read_file, write_file, edit_file, glob
|
||||
@@ -88,7 +88,7 @@ create_task, list_tasks, get_task, claim_task, complete_task
|
||||
schedule_cron, list_crons, cancel_cron
|
||||
spawn_teammate, send_message
|
||||
request_shutdown, request_plan, review_plan
|
||||
create_worktree, remove_worktree
|
||||
create_worktree
|
||||
connect_mcp
|
||||
```
|
||||
|
||||
@@ -114,7 +114,7 @@ if blocked:
|
||||
|
||||
这样 permission、log、审计都可以挂在同一个 hook 点上。Lead、一次性 subagent 和队友的工具都会先经过 `PreToolUse`；允许执行的调用会在 handler 返回后触发 `PostToolUse`。
|
||||
|
||||
对于 MCP 工具，hook 会读取发现阶段得到的元数据：标记为 `(readOnly)` 的工具可以直接运行，修改型或没有分类的工具则先询问用户。
|
||||
权限判断不会把 MCP server 自己写的 description 当成授权依据。宿主维护一组精确的已知只读工具名单，其他 MCP 工具都要询问用户。文件工具越过 `WORKDIR` 会直接拒绝，每条 bash 命令执行前都会询问。只有前台用户轮次可以弹出交互确认；异步轮次直接拒绝需要确认的操作，不和主 CLI 争抢输入。
|
||||
|
||||
### 计划与任务
|
||||
|
||||
@@ -132,7 +132,7 @@ S17 同时保留两层计划：
|
||||
S17 有两种 delegation：
|
||||
|
||||
- `task`：一次性 subagent。独立 `messages[]`，中间过程丢弃，只返回最终摘要。
|
||||
- `spawn_teammate`：持久队友线程。它按 `WORK → result → IDLE` 运行，不设固定的工具轮数上限；模型或分发失败会发出 `error`，线程清理会把未完成 assignment 释放回任务板。idle 时先等待 `MessageBus` 消息，只在超时后扫描就绪 task，并以原子操作最多认领一个。
|
||||
- `spawn_teammate`：持久队友线程。它按 `WORK → result → IDLE` 运行，不设固定的工具轮数上限；模型或分发失败会发出 `error`，线程清理会把未完成 assignment 释放回任务板。每次调用模型前都会先读取收件箱，因此直接消息和关机请求不会被连续的 tool-use 轮次饿死。idle 时先等待 `MessageBus` 消息，只在超时后扫描就绪 task，并以原子操作最多认领一个。
|
||||
|
||||
一次性 subagent 解决“上下文隔离”；持久队友解决“长期并行协作”。
|
||||
|
||||
@@ -172,7 +172,9 @@ should_run_background → start_background_task → placeholder tool_result
|
||||
后台完成 → task_notification → 下一轮注入 messages
|
||||
```
|
||||
|
||||
cron 调度器独立 daemon thread 每秒检查一次。CLI 同时监听 `cron_queue`、Lead 收件箱和已完成的后台任务，任一事件都能自动唤醒一轮 Agent。
|
||||
只有 bash 会进入后台路径。命令非零退出或 worker 抛出异常时会发出 `failed` 通知，不会伪装成成功完成。每条 Shell 命令都在独立进程组中运行；命令结束，或 Agent 经正常路径、`SIGTERM` 退出时，运行时会停止原进程组。另建 session 的进程可以离开该边界。
|
||||
|
||||
cron 调度器独立 daemon thread 每秒检查一次。durable 的一次性任务会先持久化为 `pending_delivery`，再进入队列，并保留到包含该 prompt 的模型调用成功；调用失败会放回队列，重启后也会再次入队，因此交付语义是至少一次。CLI 同时监听 `cron_queue`、Lead 收件箱和已经结束的后台任务，任一事件都能自动唤醒一轮 Agent。
|
||||
|
||||
### worktree 与 MCP
|
||||
|
||||
@@ -181,10 +183,10 @@ cron 调度器独立 daemon thread 每秒检查一次。CLI 同时监听 `cron_q
|
||||
- pending 且未被认领的 task 可以留在主工作区，也可以通过 `create_worktree(name, task_id)` 绑定独立分支和目录
|
||||
- 创建前会校验 task、名称、路径、分支和 Git registry；Git 命令失败后还会核对 registry 和分支状态，任何部分创建的 checkout 都保持未绑定并保留供人工恢复
|
||||
- idle 队友以原子操作认领一个就绪 task，assignment 同时记录 `task_id` 和有效 `cwd`
|
||||
- 队友所有文件工具都使用该 `cwd`；只有 task owner 能完成任务并清空 assignment
|
||||
- 模型可调用的 `remove_worktree(name)` 工具会拒绝绑定未完成 task 的目录，并且只移除干净 checkout；已跟踪、未跟踪和已忽略文件都会阻止它。破坏性移除属于宿主操作，需要另行取得用户确认。成功移除后会清除绑定并保留分支；若 checkout 删除后的解绑持久化失败，则报告 partial success 供人工恢复
|
||||
- 队友所有文件工具都使用该 `cwd`；只有 task owner 能完成任务，assignment 会保留到当前模型轮次结束
|
||||
- 移除保留在宿主侧的 `remove_worktree()` 函数中，模型不能调用。用户或宿主先检查任务所有权、assignment lease、后台工作和 Git 状态；破坏性移除需要另行取得用户确认
|
||||
|
||||
worktree 只改变工具的默认工作目录，用于分离 working copy，并不是安全沙箱。
|
||||
worktree 只改变工具的默认工作目录，用于分离 working copy，并不是安全沙箱。进程组清理也无法约束另建 session 的进程，因此删除保留为宿主操作。
|
||||
|
||||
MCP 负责外部能力：
|
||||
|
||||
@@ -205,10 +207,10 @@ MCP 负责外部能力：
|
||||
| skill | 不在 s16 重点范围内 | catalog in system prompt + `load_skill` |
|
||||
| compact | 不在 s16 重点范围内 | LLM 前压缩 + `compact` 工具 + reactive compact |
|
||||
| error recovery | 简化 try/except | retry / max_tokens / prompt too long |
|
||||
| background | 不在 s16 重点范围内 | 慢操作后台线程 + task notification |
|
||||
| cron | 不在 s16 重点范围内 | daemon scheduler + durable jobs |
|
||||
| background | 后台 bash + 通知 | 同一生命周期，执行路径增加 permission hooks |
|
||||
| cron | daemon scheduler + durable jobs | 同一调度器接入集成事件循环 |
|
||||
| multi-agent | 从 s15 继承 | 保留原子 task ownership 和任务级 `cwd` |
|
||||
| worktree | task 可选绑定 | 保留安全的创建和移除语义 |
|
||||
| worktree | task 可选绑定 | 模型创建，宿主检查并移除 |
|
||||
| MCP | 新增 | 保留，作为集成工具池的一部分 |
|
||||
|
||||
---
|
||||
@@ -237,7 +239,7 @@ python s17_integrated_harness/code.py
|
||||
- 队友是否提交 plan，并在 approval 前暂停
|
||||
- idle 队友是否只原子认领一个就绪 task
|
||||
- 队友所有文件工具是否都切换到已认领 task 的 `cwd`
|
||||
- 是否只有 task owner 能完成任务并清空 assignment
|
||||
- 完成任务后是否在本轮剩余工具调用中保持 task `cwd`，并在 IDLE 时释放
|
||||
|
||||
---
|
||||
|
||||
@@ -260,4 +262,4 @@ while True:
|
||||
|
||||
下一章：[s18 Workflow Runtime](../s18_workflow_runtime/) — 当编排形状固定时，把它从多轮对话移入确定性、可恢复的代码。
|
||||
|
||||
<!-- translation-sync: zh@v3, en@v3, ja@v3 -->
|
||||
<!-- translation-sync: zh@v8, en@v8, ja@v8 -->
|
||||
|
||||
Reference in New Issue
Block a user