@cr1992/agentkit 1.0.0

package/docs/orchestrate/failure-routing-and-recovery.md

@@ -0,0 +1,46 @@
+# 失败路由与 Controller 恢复
+
+只在能力故障、业务验收失败、worker 中断、重派或 controller 接手时读取。正常 happy path 不加载。
+
+## 能力故障
+
+先归一为：
+
+- `allowed`
+- `denied_by_policy`
+- `unavailable_or_unproven`
+- `approval_channel_fault`
+- `execution_fault`
+
+错误字符串只作证据。策略拒绝后缩小 scope 或交 controller；审批通道故障停止同类派发并交人；执行
+故障先诊断环境。不得扩大 scope、拿替代样本冒充目标对象，或用更强模型掩盖能力问题。
+
+## 验收失败与重派
+
+业务失败分为 `implementation_defect / reasoning_gap / context_gap / strategy_gap / environment_fault /
+contract_gap / safety / undecidable`。前四类可在已授权的本地 envelope 内选择 `retry_same /
+raise_effort / switch_model / promote_tier / fresh_context / change_strategy`；其余分别诊断环境、
+re-contract、停止或升级。
+
+每次重派创建新 attempt 和新 ledger 节点。前序先附稳定失败 report/Evidence 并进入 `failed`；新派发
+绑定直接前序 `attempt_id`、连续序号、`failure_kind`、`failure_ref` 与新的选择理由。达到
+`max_attempts`、连续同因熔断或需要越过已授权模型/effort envelope 时停止并交用户。模型动作的完整
+约束见 [model-routing-config.md](model-routing-config.md)。
+
+## Worker 中断
+
+宿主标记 `interrupted` 后，先要求原 worker 只读回报原任务、进度、产物、改动和中断原因，不继续
+业务写入。有稳定产物则验收并收养；无产物或不能恢复才判取消/未通过。模型与 effort 以 controller
+保存的派发参数和宿主回执为准，不要求 worker 自省。
+
+## Controller 接手
+
+接手按“重建 → 收养 → 重派”：
+
+1. 从仓库外快照、资源归属和宿主留痕重建任务图；冲突时以可观察证据为准。
+2. 有产物的节点重新验收后收养，不采信旧台账中的待验收/通过叙述；无法对账的资源保持
+   `KEEP + owner + 原因`。
+3. 无产物或验收失败的节点视为未派发，按现行合同创建新 attempt。
+4. 收养的 worktree、分支、进程与外部资源进入当前回收清单，继续服从原安全边界。
+
+递归派生默认禁止；只有 controller 明确给出目标、预算和最大深度时才允许，通常不超过两层。

package/docs/orchestrate/host-capability-cache.md

@@ -0,0 +1,170 @@
+# 宿主能力缓存协议
+
+能力快照用于复用已经验证过的宿主语义与限制；它是缓存，不是能力或授权的事实源。实时工具契约
+始终优先。读取本文件后，使用 `scripts/host_capability_cache.mjs` 管理状态、刷新和观察事件。
+
+宿主快照缓存只对 `orchestration_mode: full` 强制；worker 有效能力预检对所有档位生效。满足
+`SKILL.md` 轻量档全部条件时，不为 cache `status` 构造完整宿主 descriptor，但仍须证明节点实际要求的
+运行时能力。轻量档升级为完整档时，再按下文发现、检查和刷新宿主快照。
+
+## 目录
+
+- [存储与分层](#存储与分层)
+- [实时描述](#实时描述)
+- [Worker 有效能力](#worker-有效能力)
+- [检查与刷新](#检查与刷新)
+- [观察与沉淀](#观察与沉淀)
+- [安全边界](#安全边界)
+
+## 存储与分层
+
+路径根与模型路由配置相同：用户级根跨项目复用，项目级根只承载该仓库或沙箱特有约束。
+
+```text
+orchestrate-subagents/
+├── hosts/<host>.json                 # 人工偏好
+├── capabilities/<host>.json          # 自动能力快照
+└── observations/<host>/<event>.json  # 只追加观察事件
+```
+
+默认使用 `--scope global`。只有项目工具、沙箱授权或仓库运行环境改变宿主行为时使用
+`--scope project`。`--config-dir` 只用于测试或用户显式指定的配置根。
+
+## 实时描述
+
+`host` 是缓存命名空间，不是展示名。使用当前编排工具提供方 / 接口族的稳定、小写标识；不能只因
+desktop、CLI、IDE、UI、会话、版本或模型不同就增添后缀。只有工具命名空间或契约族长期独立时，
+才为运行表面使用稳定后缀。创建新 key 前，先把所选配置根已有 `capabilities/*.json` 当不可信数据
+检查：只读取通过本协议校验的 `host`、工具接口指纹和版本；若已有快照属于同一提供方与接口族、
+且实时工具接口指纹一致，复用其 `host`。不能仅凭指纹相同把两个不同提供方合并；来源仍有歧义时
+使用当前提供方 / 接口族的稳定标识、记录歧义，不覆盖任一旧快照。
+
+首次派发前，只从当前工具 schema 生成临时 observed descriptor；不能读取旧快照补齐字段。临时
+文件放宿主 scratchpad 或平台临时目录，不提交到仓库。
+
+```json
+{
+  "schema_version": 1,
+  "host": "host-a",
+  "host_version": "unknown",
+  "tools": [
+    {
+      "name": "worker",
+      "parameters": ["message:required:string", "model:optional:enum[model-a,model-b]", "effort:optional:enum[low,medium,high]"],
+      "returns": ["agent_id:required:string"]
+    }
+  ],
+  "capabilities": {
+    "dispatch.tools": ["worker"],
+    "model.explicit": true,
+    "model.discovery": "available"
+  },
+  "limits": {
+    "concurrency.max": 4
+  },
+  "unknown": ["hard-token-budget"]
+}
+```
+
+`tools[].parameters` / `returns` 的字符串必须稳定编码字段名、必填性、类型和枚举范围，而不只抄字段
+名；能力指纹只对这份规范化实时工具接口计算，所以模型列表、effort 档位或返回契约变化会使快照
+过期，而 Agent 对语义能力的不同归纳不会制造假过期。`capabilities`、`limits` 和 `unknown` 是待实时
+复核的建议性解释，不参与指纹；它们只接受扁平键与标量 / 字符串数组。脚本严格拒绝未知顶层
+字段、重复工具、路径穿越 host 和超大 JSON。宿主未暴露版本时写 `unknown`，不得猜版本号。
+
+能力键至少覆盖实际可见的 `dispatch.tools`、model / effort / budget 可调性、生命周期 wait / message /
+interrupt、隔离方式、证据来源和授权门；并发上限等数值写入 `limits`。缺失或无法证明的项目写入
+`unknown`，不能为了让快照完整而推断。`model.discovery` 只接受 `available / unavailable`；自由字符串
+参数但没有候选枚举或可审计列举接口时写 `unavailable`，不以缺失的 `hosts/<host>.json` 代替该事实。
+
+## Worker 有效能力
+
+工具 schema 不证明 worker 能否执行命令、读哪些路径或完成审批往返。每个节点先生成
+[Worker Capability Requirements v1](../../schemas/worker-capability-requirements-v1.schema.json)，再用与当前
+host、worker profile、接口指纹和 session / 配置 binding 相符的
+[Effective Worker Capability v1](../../schemas/effective-worker-capability-v1.schema.json) 检查：
+
+```text
+agentkit orchestrate preflight check \
+  --requirements <requirements.json> [--effective <effective.json>]
+```
+
+有效记录默认放仓库外的当前 session state root；`session:<opaque>` 最长有效 24 小时，能稳定获得宿主
+agent 配置摘要时可用 `config:sha256:<digest>`，最长 168 小时。配置或 session 无法绑定时不能把探针
+结果跨会话当事实复用。结果只用以下语义，不把错误字符串写成规则：
+
+| outcome | 含义与动作 |
+|---|---|
+| `allowed` | 能满足该 required capability |
+| `denied_by_policy` | 已知策略拒绝；缩小节点或交 controller |
+| `unavailable_or_unproven` | 未证明；按成本选择最小探针、缩小范围或 controller 自做 |
+| `approval_channel_fault` | 审批往返故障；停止同类派发并升级给人 |
+| `execution_fault` | 执行环境故障；停止同类派发并诊断 |
+
+最小探针只覆盖当前任务缺少的能力，不固定探测所有路径或命令。探针是实际 worker，计入 worker 数、
+预算和台账。记录必须引用探针、schema 或 observation 的稳定摘要；接口指纹、binding 或有效期不匹配
+时 fail closed。升级为 full 只增加 ledger、恢复和缓存，不改变这些能力结果。
+
+## 检查与刷新
+
+安装 Node.js 22+ 与 `agentkit` 后运行：
+
+```text
+agentkit host cache status --host host-a --repo <git-root> --observed <current-observed.json>
+```
+
+状态语义：
+
+- `fresh`：版本、有效期和能力指纹一致。仍须实时确认本次使用的工具与参数。
+- `absent`：没有快照，执行完整发现后刷新。
+- `stale`：快照过期、损坏，或版本 / 指纹变化，禁止继续依赖旧值。
+
+刷新默认有效期 168 小时，可在 1–2160 小时内调整：
+
+```text
+agentkit host cache refresh --host host-a --repo <git-root> --observed <current-observed.json> --ttl-hours 168
+```
+
+快照使用规范化工具接口的 SHA-256 指纹和原子替换写入。宿主版本、有效期或工具接口变化会触发
+重建；建议性 `capabilities / limits / unknown` 变化先按当轮实时契约复核，不单独触发重建。即使状态
+是 `fresh`，实时调用返回“不支持”、参数拒绝或授权语义冲突时也必须立即判 `stale`，停止依赖缓存
+并重新生成。
+
+快照固定使用 `source: live-tool-schema`。`generated_at` 不得比检查时间超前五分钟以上；
+`expires_at` 必须晚于生成时间，且两者间隔不得超过 2160 小时。来源、时间窗、缓存内 observed
+descriptor 或其指纹任一无效时都返回 `stale`，不得仅因过期时间仍在未来而信任快照。
+
+## 观察与沉淀
+
+运行中发现与快照不一致的宿主能力事实（如参数名不同、并发超出限制、被静默降级）时，用脚本追加一条
+结构化观察：
+
+```text
+agentkit host cache observe --host host-a --repo <git-root> --event <event.json>
+```
+
+事件格式：
+
+```json
+{
+  "schema_version": 1,
+  "category": "rate_limit",
+  "summary": "并发超过 4 时报 HTTP 429",
+  "confidence": "reproduced",
+  "evidence": {"observed_limit": 4},
+  "portable": true
+}
+```
+
+`confidence` 只能填 `observed-once`、`reproduced` 或 `schema-confirmed`。观察是待验证线索，
+不直接改写能力快照，下一次 `refresh` 重新发现。落盘记录使用
+`{ schema_version, host, recorded_at, capability_fingerprint, event }`；`event` 保存上述输入字段。只有格式
+为 `sha256:<64 hex>` 的缓存指纹可绑定到观察，损坏或不可读快照一律记录 `null`。
+
+`observations/<host>/` 只承载宿主能力事实。合同、路由、验收或 Skill 缺口使用编排 Reflection；轻量档
+通过 `orchestration-reflection.mjs` 记录，不能为了绕过 ledger 要求把通用 reflection 伪装成 host 观察。
+
+## 安全边界
+
+能力快照和观察记录只应保存可公开的工具 schema 与运行指标；严禁在 `capabilities`、`limits` 或
+`evidence` 中记录 token、凭证、私有 URL、设备标识或敏感 payload。

package/docs/orchestrate/isolation-fallback.md

@@ -0,0 +1,18 @@
+# 无 manage-worktrees 时的隔离下限
+
+仅在已经裁决需要 worktree、但 `manage-worktrees` 不可用时读取。专项 Skill 可用时服从其 runtime，
+不要同时执行本 fallback。
+
+1. **建树**：controller 按项目规则刷新 base，在仓库外的 durable 临时位置创建独立分支与 worktree。
+   已有目录或分支先判定归属并复用；禁止 `rm -rf` 重建，宿主临时树语义不明时不用。
+2. **worker 边界**：合同固定 repository、workdir、branch 与 writable paths；worker 不换目录，不执行
+   merge、stash、push 或创建 MR，环境异常立即报告 `blocked`。
+3. **共享资源**：worktree 只隔离 working directory 和 index，不隔离 refs、端口、进程、数据库或
+   外部服务；实际使用的共享资源必须分配 owner 并登记。
+4. **验收集成**：controller 在 worker 树内重跑门禁，再在已确认目标分支的集成树中串行合回并重验；
+   重验 diff 使用 base 到 HEAD 的范围，不能依赖 merge 后为空的 staged diff。merge clean 不代表语义兼容。
+5. **保守回收**：任务、路径、分支和 owner 可对账，树与 untracked 均 clean，成果已验收合入，仓库无
+   stash，四项全部满足才运行不带 `--force` 的 `git worktree remove`；否则 `KEEP + 原因`。
+
+共享树写入时 controller 是唯一 integrator。worker 只能按归属 pathspec stage/commit，禁止切分支、
+`git add -A`、`git commit -am`、裸 stash、`reset --hard`、`checkout -- .` 和并发 merge。

package/docs/orchestrate/model-routing-config.md

@@ -0,0 +1,186 @@
+# 本地模型路由与动态调整
+
+模型路由只保存用户在当前宿主上的执行偏好。Skill 不内置具体模型名、供应商排序、价格、上下文长度，
+也没有任何预设档位或按角色 / 任务的路由表；tier 只来自用户配置。
+最强适配 Controller 根据节点难度和验收证据选择本地 tier；脚本只负责校验选择是否在用户配置、
+宿主实时能力和动态调整上限内。
+
+## 配置位置
+
+每个宿主只有一个用户级文件：
+
+```text
+<user-config-root>/
+└── hosts/
+    └── <host>.json
+```
+
+用户配置根：
+
+| 平台 | 默认位置 |
+|---|---|
+| Windows | `%APPDATA%\agent-skills\orchestrate-subagents`；缺失时回退 `%USERPROFILE%\AppData\Roaming\...` |
+| macOS | `~/Library/Application Support/agent-skills/orchestrate-subagents` |
+| Linux | `$XDG_CONFIG_HOME/agent-skills/orchestrate-subagents`；未设置时 `~/.config/agent-skills/...` |
+
+`ORCHESTRATE_SUBAGENTS_CONFIG` 可覆盖配置根。仓库内配置不参与模型与成本路由，避免项目文件静默
+改变用户的模型消费偏好。不同宿主独立配置，不从另一宿主复制或猜测模型 ID。
+
+## 配置结构
+
+下面是贴近“强 Controller + 主力 + 杂活”偏好的**非规范性占位示例**。现场必须用当前宿主实际
+暴露的精确 ID 替换 `provider-*`；示例名称不是内置型号：
+
+```json
+{
+  "schema_version": 2,
+  "host": "host-a",
+  "effort_order": ["low", "medium", "high", "xhigh"],
+  "tier_order": ["utility", "primary", "frontier"],
+  "tiers": {
+    "utility": {
+      "models": ["provider-utility-current"],
+      "effort": {"default": "xhigh", "min": "medium", "max": "xhigh"},
+      "channel": "worker",
+      "dispatch": "explicit"
+    },
+    "primary": {
+      "models": ["provider-primary-current"],
+      "effort": {"default": "xhigh", "min": "medium", "max": "xhigh"},
+      "channel": "worker",
+      "dispatch": "explicit"
+    },
+    "frontier": {
+      "models": ["provider-frontier-current"],
+      "effort": {"default": "high", "min": "medium", "max": "xhigh"},
+      "channel": "worker",
+      "dispatch": "explicit"
+    }
+  },
+  "dynamic_adjustment": {
+    "enabled": true,
+    "max_attempts": 3,
+    "allowed_actions": [
+      "retry_same",
+      "raise_effort",
+      "switch_model",
+      "promote_tier",
+      "fresh_context",
+      "change_strategy"
+    ]
+  }
+}
+```
+
+- tier 名称和数量由用户定义；`tier_order` 从低到高排列，脚本不猜模型强弱。
+- `models` 是有序候选；解析器选择当前宿主实时可用的第一个候选。
+- `effort.default` 是普通派发默认值，Controller 可在 `min..max` 内按节点和失败证据调整。
+- `channel / dispatch` 必须能由当前宿主工具契约验证。
+- `max_attempts` 包含首次派发；达到上限后停止，不通过改配置现场绕过。
+
+上述示例表达一种合理个人偏好：复杂、高模糊、高爆炸半径任务用 `frontier`，日常实现和评审用
+`primary`，边界清楚的提取、扫描、格式化等工作用 `utility`。三个 tier 都可以使用较高 effort；
+便宜来自模型选择，不强制来自低 effort。最终选哪个 tier、是否降低或提高 effort，由最强适配
+Controller 根据任务证据判断。
+
+## 首次配置与修改确认
+
+配置文件不存在时，Controller 只根据宿主实时 schema 形成候选表，展示 tier、精确模型、effort
+范围、默认值、成本/质量影响和目标文件。不得凭记忆写型号，也不得先保存再让用户追认。
+
+以下动作需要用户确认：
+
+- 首次写入本地配置；
+- 增加新模型、提高 effort 上限或增加最大尝试数；
+- 替换 tier 顺序或默认模型，且可能明显影响质量或成本；
+- 宿主候选变化导致原配置失效。
+
+已有合法配置就是用户授权的动态调整 envelope。在其模型候选、effort 范围、动作集合和尝试上限内，
+Controller 可以根据当轮证据自主调整，不逐次询问；超出 envelope 时停止并展示待确认变更。
+
+## Controller 选择 tier
+
+Controller 不按 worker 的角色名机械路由，按节点实际决策杠杆选择：
+
+| 节点特征 | 常见选择 |
+|---|---|
+| 输入完备、输出机械、错误容易由测试发现 | 较低 tier |
+| 日常实现、局部评审、常规跨文件修改 | 中间或默认 tier |
+| 高模糊、跨系统、隐蔽错误、高爆炸半径、关键对抗核验 | 较高 tier |
+
+这只是启发式，不把 tier 名称写死成 `utility / primary / frontier`。Controller 必须记录
+`selection_reason`，说明为何当前配置是最低可靠选择。
+
+## 验收失败后的动态调整
+
+先把失败归一为：
+
+| `failure_kind` | 处置 |
+|---|---|
+| `implementation_defect` | 可定向重试、换策略或按证据提升配置 |
+| `reasoning_gap` | 可提高 effort、切模型或提升 tier |
+| `context_gap` | 优先新上下文；必要时切模型或提升 tier |
+| `strategy_gap` | 改策略、切模型或提升 tier |
+| `environment_fault` | 诊断工具、权限或依赖；不得用模型重路由掩盖 |
+| `contract_gap` | 停止并 re-contract |
+| `safety` | 停止或进入人工门 |
+| `undecidable` | 停止并升级 Controller / 用户 |
+
+允许的重路由动作：
+
+- `retry_same`：配置不变，只携带精确 finding 定向重试；
+- `raise_effort`：同 tier、同模型，effort 沿本地顺序提高；
+- `switch_model`：切换到本地 envelope 内另一模型；
+- `promote_tier`：沿 `tier_order` 向更高 tier 移动；
+- `fresh_context`：模型参数不变，换干净 Worker 上下文；
+- `change_strategy`：保留失败事实但替换实现策略。
+
+不要固定成“第 N 次必升模型”。Controller 先判断失败是实现缺陷、推理、上下文还是策略问题；
+环境、合同、安全和不可判定失败不能通过重路由继续试错。每次重派都必须绑定前序 attempt、失败类型、
+稳定失败证据摘要和选择理由。
+
+## 解析器
+
+首次派发：
+
+```text
+agentkit host model-policy \
+  --host host-a \
+  --tier primary \
+  --selection-reason "常规跨文件实现使用本地主力层" \
+  --available-model <live-model-id> \
+  --available-effort <live-effort> \
+  --available-channel <live-channel>
+```
+
+失败后由 Controller 选择调整方式，并把上一份解析结果作为 lineage：
+
+```text
+agentkit host model-policy \
+  --host host-a \
+  --tier frontier \
+  --attempt 2 \
+  --previous-dispatch <attempt-1.json> \
+  --action promote_tier \
+  --failure-kind reasoning_gap \
+  --failure-ref sha256:<digest> \
+  --selection-reason "验收显示跨模块推理遗漏，提升到更高本地 tier" \
+  --available-model <live-model-id> \
+  --available-effort <live-effort> \
+  --available-channel <live-channel>
+```
+
+解析器验证配置 schema、实时候选、effort 上下限、tier 顺序、动作语义、前序 attempt、失败摘要和
+最大尝试数。它不判断业务失败原因，也不直接派发 Agent；Controller 对分类与选择负责。
+
+解析结果是独立的 [`model-policy-resolution` schema v1](../../schemas/model-policy-resolution-v1.schema.json)，
+不是 ledger 的 `dispatch-record` schema v2。
+结果中的 `dispatch_record_patch` 已直接使用 dispatch 字段名。Controller 必须补齐
+`schema_version: 2 / worker_id / orchestration_mode / capability_source / capability_fingerprint /
+token_budget`，再与该 patch 合并后交给 `dispatch-record`；不得把整个解析结果或不完整 patch 直接
+写入 ledger。解析结果顶层的 `host / channel / tier_rank / selection_source` 是派发控制信息，不属于
+ledger dispatch。下一次重派的 `--previous-dispatch` 接收上一份完整解析结果，以校验 attempt lineage。
+
+宿主无法列举模型时，持久本地配置不能验证并阻塞。只有用户当轮同时明确给出的精确 `--model` 与
+`--effort` 才可配合 `--user-explicit` 继续，并标记 `user-explicit-unverifiable`；单独传 flag 或省略
+任一显式值都拒绝，不得把旧配置静默标成用户授权。