@fooksky/lodestar 0.2.2 → 0.2.3

package/docs/design.md

@@ -1,342 +0,0 @@
-# DSH 原生开发工作流首版设计
-
-> 历史范围：本文保留 `0.1.0` 首版设计和当时的验证记录。开发中的 `0.2.0` 分支扩展以 [分支与 worktree 隔离设计](branch-management.md) 为具体契约；涉及 schemaVersion、工具 action、项目根边界、worktree 与恢复的差异，以该扩展为准。下文的首版字段及“不强制 worktree”等表述不代表扩展后的规则。
-
-日期：2026-11-07。状态：首版设计、按需角色指引及可选开发模式均已获用户确认，用户已授权实施。首版代码已实现，程序及已安装宿主集成测试通过；未安装到本地/profile。真实模型行为验收尚未执行，状态见 [场景记录](../tests/scenarios.md)。
-
-依据：[提案 v0.4](proposal.md)。用户已确认：材料统一在 `.dev-docs/`，复用已有长期知识；首版插件负责 change 状态结构化读写，skill 负责工作流语义判断，DSH 原生能力负责任务执行；未来 hook 复用状态入口。本文已整合这些决定，替代此前纯 skill 与状态全放 plan 的草案。
-
-## 1. 目标和范围
-
-交付独立 DSH bundle，包含一个 `dev-workflow` skill 和一个 `lodestar_change` 状态工具。用户用自然语言开始或继续工作，不需要学习命令族。
-
-主流程：意图澄清及用户确认 → 具体方案及用户审核 → AI 生成 plan → 原生执行与必要验证 → 交付及必要知识更新。新项目按真实可运行的功能切片推进，同样遵循此流程。
-
-插件负责材料关联、change 状态、确认来源引用、验收结论索引和恢复信息；不执行或调度开发任务，不重做 Team、goal、压缩、浏览器、权限系统。首版没有数据库、新 UI、常驻文件 watcher、自动提交、推送、发布或安装。
-
-结构化工具可以阻止自身状态发生非法转换，不能阻止模型通过其他文件工具越过流程实施。确认来源的语义仍由 Lead 判断，不声称宿主级强制审批。自动安装到本地/profile 始终需要独立明确授权。
-
-## 2. 已核对的宿主接口
-
-本机核对基线为 DSH `0.2.2-rc.1`。以下来自公开类型与官方 Host 插件说明，尚不是运行验证结果。
-
-| 能力 | 已核对接口 | 设计用途 |
-|---|---|---|
-| Bundle | `dsh.bundle.patch` | 独立 Host 插件 |
-| Skill | `ctx.skills.register`，返回 disposer | 注册入口及包内资源位置 |
-| Tool | `ctx.tools.register`，返回 disposer | 注册状态工具，声明输入和 canonical output schema |
-| 工具结果观察 | `tools/result(exec, result)` | 后续订阅最终冻结结果；监听器错误由宿主隔离 |
-| 工具策略事件 | `tools/pre-execute`、`tools/execute`、`tools/post-execute` | 当前不使用，不改写其他工具策略或结果 |
-| 文件解析与边界 | `ctx.fs.resolve`、`contains` | 路径解析及材料目录包含关系 |
-| 文件读写 | `stat`、`readText`、`writeText` | 用 `createIfAbsent` 或 `replaceIfVersion` 原子写入 |
-| 原生 Team | 当前可用 `team_task_*`、成员与消息工具 | Agent 直接调用，不包装成第二执行引擎 |
-
-工具注册必须提供 `output.schema` 和 `output.render`；执行函数接收调用上下文并遵守取消信号。项目文件通过调用方对应的宿主文件能力和实际 sandbox policy 访问，不通过裸 Node fs 绕过会话权限。Node 文件读取只用于插件自己的随包只读资源。
-
-已进一步核对原生文件工具调用链：通过 `ctx.workingDirectory.ensure(exec.agent, exec.signal)` 获取调用 Agent 的当前目录，作为 fs.resolve 的 cwd；通过 `ctx.sandboxPolicy.resolve({ session: exec.agent.session })` 获取会话实际策略并传入 writeText。权限中的 workspace root 来自宿主会话策略，不由工具传入的 projectRoot 覆盖。projectRoot 只选择材料位置，不扩大授权边界。
-
-首版工具要求存在调用 Agent，不接受缺少会话身份时退回进程 cwd。需要隔离的服务使用调用 Agent 对应的 scope；集成测试验证不同会话不会串用目录或策略。文件 backend 提供 sandboxMode 时必须有 sandboxPolicy；非沙箱 backend 沿用宿主无策略语义。首版不提供自行提权参数，拒绝写入时原样报告权限问题；不临时换路径或裸 fs 重试。上述来自原生代码核对，尚待运行集成验证。
-
-首版不依赖尚未核对的 Team 专用事件，也不假定 `tools/result` 是持久、可回放或 exactly-once 事件流。
-
-## 3. 模块与数据归属
-
-```text
-用户 ↔ Lead / dev-workflow skill
-          ├─ 原生 Teams、文件、测试、浏览器等工具
-          ├─ Markdown 需求、方案、计划及知识
-          └─ lodestar_change 工具
-                  ↓
-             状态更新模块 ← 后续原生事件适配器
-                  ↓
-             宿主文件能力
-                  ↓
-             state.json
-```
-
-| 模块 | 职责 |
-|---|---|
-| Host 入口 | 注册 skill/tool、依赖与生命周期清理 |
-| Skill 及阶段参考 | 需求与方案判断、确认复用、任务组织、验证与交付 |
-| Tool 边界 | 参数 schema、调用者上下文、错误和有界结果展示 |
-| 状态模块 | 领域操作、前置条件、材料版本关系、状态变更 |
-| 文件仓储 | 路径边界、读写版本、原子发布、读取损坏报告 |
-| 后续 hook 适配器 | 将可识别原生事实映射为有限观察记录，调用同一状态入口 |
-
-状态模块不依赖模型工具调用形式；以后 hook 可以直接调用其内部方法。首版不注册 hook，只建立可复用模块边界。
-
-Markdown 是语义正文的权威；state 是本工作流状态和关联的权威；DSH 是原生执行事实的权威。state 中的原生引用或观察不反向覆盖 Team。程序不会从“任务全部完成”推断“需求已满足”。
-
-## 4. 文件布局与知识复用
-
-```text
-.dev-docs/
-  index.md
-  knowledge/                    # 沿用已有主题，不强制目录模板
-  changes/
-    <change-id>/
-      intent.md
-      spec.md
-      plan.md
-      state.json
-    archive/                    # 保留已有历史
-  artifacts/                    # 按需，避免复制宿主已有大日志
-```
-
-默认 change ID 为 `YYYYMMDD-short-slug`，冲突才增加短后缀。ID 是稳定身份，标题可修改；目录名不表达当前状态。根目录由当前项目及用户范围确定，工具每次显式接收 `projectRoot`，不维护全局“当前 change”。非 Git 项目使用明确工作目录。多候选恢复时先列标题与状态，无法确定再请用户选择。
-
-复用本 worktree 的 `.dev-docs/index.md`、`knowledge/` 和已有项目文档，不重命名或添加强制 frontmatter。工作流确认与完成记录必须引用实际用户表达和验收证据。
-
-项目材料可纳入版本控制，但不自动暂存或提交。完成后保留 change 原路径，状态设为 done；不增加自动搬移归档流程。大截图与日志以引用为主，需要长期保留时才放 artifacts。list 对未受管目录按常规读取规则报告缺失或非法 state 错误，不自动初始化或重建。
-
-## 5. 人可读材料
-
-### 5.1 intent
-
-保存原始诉求或准确引用、真实需求、使用场景、目标、范围/非目标、重要约束及待明确问题。用户纠正后更新当前内容，关键理由就近记录。不把模型猜测当作确认需求。
-
-### 5.2 spec
-
-保存预期行为、影响范围、模块职责和数据流、必要接口/数据变化、关键取舍及验收要求。验收项使用稳定 `A1、A2…`；编号删除后不分配给新含义。spec 引用 intent，不复制背景全文。
-
-### 5.3 plan
-
-保存实施步骤、依赖、写入范围、验证方法及取舍。步骤可用 `P1、P2…`，关联验收 A 编号。原生任务绑定、动态进度与验证结果保存在 state，不手动重复勾选。
-
-Team 模式任务状态只从原生任务板获取；直接执行时 state 可保存步骤进度。两者按步骤明确模式，不把 Team 步骤的 status 再保存一份。
-
-三份正文按规模撰写，每份可只有几行，无强制篇幅。仅 Lead 修改主材料。intent 在澄清时创建，spec 在设计时创建，plan 在实施授权后创建；不预建空模板树。
-
-### 5.4 长期知识
-
-长期知识继续用 Markdown，保存当前稳定事实、约束、架构与运行方法。既有 README/架构文档只引用，不复制。知识入口只路由主题，不维护第二张 changes 列表。
-
-如有真实检索需求，可在新增或实际修改主题中添加少量 YAML frontmatter（稳定 id、关联 change）；首版不要求。未来检索索引应能从正文重建。调试过程、工作进度和临时猜测不沉淀为长期知识。Mnemon 和 BrowserSkill 均可选。
-
-## 6. state.json 的领域结构
-
-采用 JSON，UTF-8、两空格缩进、文件末尾换行；机器写入，不要求用户手工编辑。YAML 留给确有人工配置需求的场景，不同时维护 YAML/JSON 状态副本。
-
-| 字段 | 结构及职责 |
-|---|---|
-| schemaVersion | 仅接受整数 2；未知或旧版本拒绝，不猜测转换 |
-| workspace | 必填；当前分支或普通目录的持久绑定，具体结构见分支隔离设计 |
-| workspaceHistory | 重绑历史；每项的 previous、reason、recordedAt 必填 |
-| id、title | 稳定 change ID 和显示标题 |
-| revision | 每次成功状态变更递增，初始为 1；用于调用方 CAS |
-| createdAt、updatedAt | 由插件生成的 UTC 时间，仅描述写入时间 |
-| documents | intent/spec/plan 的当前登记版本、相对路径、内容摘要与依赖 |
-| workflow | phase、status、reason、nextAction |
-| decisions | 用户确认/审核/实施授权及撤回的引用记录 |
-| acceptance | 当前验收 ID、spec 版本、定位锚点、是否 required |
-| execution | 步骤与验收关联；direct 或 native 模式；原生来源引用 |
-| verification | 验收结论、适用版本、被测对象/环境、证据引用 |
-| blockers | 尚未解决的具体缺口及其解决记录 |
-| closure | done 时的交付说明与证据关联；未完成时缺省 |
-
-不保存工具全文输出、完整聊天或图片。记录数组使用工作项内稳定 ID；修正已有结论用新记录标明 supersedes，避免原结论静默变成另一个事实。首版不建立通用事件日志。
-
-文档登记项包含 `version`（正整数）、`path`、`digest`（规范化换行后正文 SHA-256）、`basedOn`（spec 对 intent，plan 对 intent/spec）。首次为 1，语义变化递增；纯排版修改可更新 digest 并提供理由，不递增语义版本。所有正文应由宿主文件工具写好后再登记，插件不生成或重写正文。
-
-摘要用于发现登记后正文变化，不能判断语义。get 返回检测结果而不偷偷改状态；正文不匹配时，新的确认与推进操作拒绝继续，要求先登记变化。格式修订必须由 Lead 声明，不由程序从 diff 自动推断。
-
-文档修改与 state 更新不是多文件事务；“正文先成功、登记未完成”是允许恢复的中间状态，恢复通过 digest 不匹配识别。重要转换前核对文档版本；不承诺在其他 Agent 同时写正文时实现跨文件隔离，主材料仍为单 owner。
-
-## 7. 确认、版本与验证记录
-
-### 7.1 确认记录
-
-decision 字段：`id`、`kind`、`subjects`（材料及语义版本）、`scope`（全范围或具体差异）、`source`、`recordedAt`、可选 `supersedes/revokes`。kind 为 `intent-confirmation / spec-review / implementation-authorization / revocation`。
-
-source 保存真实用户表达的短摘录，能取得时附 session ID 和 event seq；没有可定位事件时保存当前用户表达与上下文说明，标记为 Agent 记录，不伪造事件号。程序检查结构和版本关联，不声称能证明用户语义或防伪。
-
-同一句“需求和方案没问题，按这个做”可在一个状态更新中登记三类决定，引用同一来源。“设计没问题，先别做”只登记审核，不登记实施授权。用户跳过、沉默、工具审批通过或 goal 续轮都不是决定来源。
-
-语义升版后旧决定保留历史但不适用于新版本；用户已明确批准本次差异时，新增覆盖新版本的决定并引用该表达，无需重问。排版更新不自动撤回确认。恢复可以复用来源明确、范围匹配且未撤回的记录；来源模糊时才定向查询历史或询问。
-
-### 7.2 验收与验证
-
-acceptance 是验收索引，不复制 spec 的全部文字。修改 spec 后 Lead 显式提交当前索引，程序核对 ID 唯一及引用存在，语义对应由 Lead 判断。
-
-verification 字段：`id`、`acceptanceIds`、`specVersion`、`outcome`、`method`、`subject`、`environment`、`evidenceRefs`、`summary`，可选 `supersedes` 或 `carriedFrom`。outcome 为 passed/failed/not-run/not-applicable/stale。时间由插件记录；实际观察时间可单独提供。
-
-passed 必须有依据引用；not-applicable 必须说明原因，并且不能满足仍标为 required 的验收。必需项取消必须修订方案索引，不能靠“不适用”绕开。
-
-需求、相关实现、验证方法或环境变化后，Lead 标记受影响记录 stale。新 spec 下可以显式沿用仍有效的结果，生成引用旧证据的新记录并说明适用理由；版本变化不要求全量重跑。compact、任务重排、无关文档修改不自动失效。
-
-被测对象需要足够定位实际产物：未提交修改不能只用 HEAD，远端页面不能只用 URL。程序不维护全代码依赖图，不自动证明证据仍适用。
-
-## 8. 工具 API
-
-仅暴露 `lodestar_change`，以 action 区分四类操作。每次提供 projectRoot；changeId 是单一路径段，不能包含目录跳转。所有路径经宿主解析，并限定在当前授权项目的 `.dev-docs/changes/<id>/` 内；证据外部路径只作引用，不作为写入目标。不会接受任意 state 文件路径。
-
-| action | 输入 | 输出 |
-|---|---|---|
-| list | projectRoot、可选 limit/cursor | change 标题、ID、阶段、revision；不读取全部正文；默认 20 条 |
-| get | projectRoot、changeId、可选 section | 当前状态或指定部分、材料一致性检查、当前阻断 |
-| create | projectRoot、changeId、title | 创建初始 state；已有目标时报冲突，不覆盖 |
-| update | projectRoot、changeId、expectedRevision、operations | 原子提交全部操作，返回新 revision 和变更摘要 |
-
-update 为一组有类型的领域操作，不接受任意 JSON Patch 或全文件替换：
-
-| operation | 关键输入与约束 |
-|---|---|
-| register-document | kind、semantic/format 分类、basedOn、reason；插件读取固定文件并计算 digest |
-| record-decision | 决定类型、当前 subjects、source、scope；可登记撤回 |
-| set-acceptance | 当前 specVersion 与验收索引；不得引用未登记 spec |
-| bind-step | stepId、acceptanceIds、mode；native 附原生引用，direct 附初始进度 |
-| set-step-progress | 仅 direct 步骤，pending/in-progress/completed 及必要说明 |
-| record-verification | 验证记录及证据引用；只能引用已登记验收 |
-| invalidate-verification | 验证 ID 集合、明确失效原因 |
-| set-blocker | 稳定 blocker ID、说明、open/resolved、解决依据 |
-| set-workflow | 目标 phase/status、reason、nextAction；通过阶段约束才保存 |
-| close | 交付摘要、必需验收关联、需求满足说明与知识处理结论 |
-
-一个 update 可原子登记一条用户表达产生的多项决定。每次最多 32 个操作，防止把完整运行日志作为一次更新。相同记录 ID 且内容相同可视为无变化，不增加 revision；同 ID 不同内容报冲突。不会因失败而部分提交。
-
-成功输出包含 `id/revision/changed/summary`；get 的全文状态按 section 返回，不自动附带 Markdown 正文。失败返回稳定分类及修正信息：NOT_FOUND、ALREADY_EXISTS、REVISION_CONFLICT、DOCUMENT_CHANGED、INVALID_TRANSITION、INVALID_REFERENCE、INVALID_STATE、UNSUPPORTED_SCHEMA。文件权限及取消等宿主错误保留原上下文，不转为默认成功。
-
-修改失败后 Agent 重新 get 并重做所需语义合并，不盲目重发。回执丢失时先 get 核对具体记录 ID 与内容，再决定是否重试。工具不提供删除 change、搬移历史或自动覆盖损坏状态的 action。
-
-## 9. 阶段约束
-
-phase：intent/spec/plan/execute/deliver/done。status：active/waiting-user/blocked/paused；done 时 status 为 active，表示已正常闭环，不另复制 completed 状态。
-
-| 推进 | 工具可检查条件 | Lead 必须判断 |
-|---|---|---|
-| intent → spec | intent 已登记且存在当前版本确认 | 用户真实需求已识别 |
-| spec → plan | 当前 spec 依据当前 intent；当前审核与实施授权存在 | 具体方案足够可实施 |
-| plan → execute | plan 依据当前 I/S；验收索引、步骤及关联有效 | 实施路径和验证合理 |
-| execute → deliver | 所有 required 验收有当前有效 passed；无 open blocker | 真实需求满足、集成完整 |
-| deliver → done | close 材料齐全，前述约束仍满足 | 可交付，无需继续扩张范围 |
-
-任意目标阶段都检查该阶段及其前置阶段的全部条件，不能用 set-workflow 跳过审核。进入 done 只能使用 close；set-workflow 可以退回已完成项，但不能直接设置 done。必需验收集合不得缺失；若任务确实没有适用验收，必须先在已审核 spec 中说明，并登记显式无适用验收的依据，不能靠空集合自动通过。
-
-调查可在确认前进行，但不写业务实现、脚手架或原型。仅要求设计时，到 spec 后交付方案并停止；不创建实施 plan 或使用 goal 推进编码。
-
-重要材料语义升版的同一 update 必须将阶段退回相应层：intent/spec/plan。系统不允许旧阶段留在 done/execute 而依据已经失效；同一更新若也登记了明确的新决定，可在最终校验通过后进入允许阶段。不机械要求固定轮数。
-
-局部修代码或调整分工不更改需求与框架方案，不重新审批。方案改变先暂停受影响成员；用户新增独立需求创建独立 change，只有用户明确纳入当前范围时才修订当前 intent。done 后的新独立需求不自动 reopen 旧项；原交付问题可通过 set-workflow 退回对应阶段并记录原因。
-
-暂停、等待、阻断均保留阶段。用户说“继续”解除的是暂停/恢复执行意图，不自动填补缺失的需求或方案决定。
-
-## 10. 存储一致性与并发
-
-每次 update：解析边界 → 读取有效 state 及宿主版本 → 比较 expectedRevision → 应用领域操作 → 检查最终状态及涉及材料 → revision 加一 → `writeText` 携带 replaceIfVersion 发布。create 使用 createIfAbsent。
-
-读取采用 stat/read/stat 稳定观察，版本变化则返回冲突要求重读，避免把旧正文与新文件版本错误配对。并发写入最终由宿主条件写入裁决。复用宿主原子写入及版本保证，不自行实现锁文件、重试循环或 JSON 双份备份。
-
-插件只能协调遵循接口的写入；人工改 JSON、跨进程外部修改的保护强度服从宿主 backend 的保证。schema 错误或损坏必须可见；不能用空对象重新初始化。首版不支持多个独立 Lead 同时拥有同一 change 的主材料，状态 CAS 不等于业务所有权锁。
-
-仅接受 schemaVersion: 2 且 workspace 完整的状态。未知或旧 schema、缺失绑定均报错，不转换或覆盖；bind-workspace 只能重绑有效状态，不能修复这些错误。
-
-## 11. 原生协作与未来 hook
-
-小任务 Lead 直接执行，有界独立调查使用 subagent，有清楚的并行工作包时使用 Teams；不固定成员数、评审人数或强制 worktree。
-
-原生任务包含目标、A/P 引用、必要资料、交付内容、write_scopes 和依赖。成员按 list/get/claim/update 的 revision 契约工作。write_scopes 只是提示，重叠文件必须指定 owner 或串行交接。依赖就绪不自动唤醒成员，Lead 显式发送消息。inactive 不等于 completed，completed 不等于业务验收通过。
-
-成员通过原生任务/消息返回结果；Lead 更新主材料和 change 状态。状态工具首版不额外实现 Lead 身份鉴权，但 skill 明确单 owner。必要的宿主权限检查仍沿用原生机制。
-
-后续第一类 hook 推荐只观察 `tools/result`，按已绑定 session/call/任务及明确工具类型映射。没有可证明关联的事件忽略，不能按“最新 change”猜归属。首先接入可验证的工具成功/失败与原生查询观察，不截获或替换其他工具结果。
-
-适配器调用内部 `recordObservation`，该方法只更新 namespaced observations，不得创建用户确认、审核、passed 验收或 done。首版无需为此创建空 observations 字段。原生状态只是带来源、观察时间的缓存，关键决策仍查询宿主。
-
-`tools/result` 没有提供持久回放保证：重复按调用身份与结果种类去重；迟到事件不能按到达时间覆盖更新的源 revision；没有可比较 revision 时只标记需要重新查询，不猜全序。漏事件由恢复时原生查询补齐。同步写入失败应留下可见诊断，不改变原工具已经发生的结果，不承诺 exactly-once。
-
-hook 注册必须按 scope 隔离，并在插件卸载时清理；不会扫描其他无关会话。首次 hook 迭代需核对实际 Team 输出契约、来源身份和事件覆盖，再确定映射，不依赖私有日志文件。
-
-## 12. 验证、收敛与恢复
-
-plan 选择与风险相称的静态检查、测试、构建、API/CLI 和浏览器验证。替代方法需证明同一命题；fixture、截图生成、编译通过不能各自冒充真实集成、实际观察或交互验收。
-
-视觉检查只覆盖相关场景，按小包及时记录结论。已有明确全量覆盖要求时必须完成，不能静默抽样。连续两次同类失败无新证据时改变诊断或方法，不降低标准。已满足需求与规格且必需验收通过即收敛，新增想法不扩大范围。
-
-恢复顺序：显式 change 或确定绑定 → get 状态和一致性提示 → 当前 intent/spec 及 plan 相关段 → 必要源代码/产物 → 原生任务与成员 → 缺口对应的历史事件。避免全量读取旧对话与知识。
-
-同会话查询实际任务和仍在写入的成员；跨会话旧 Team 不可达时，核对已有成果并只为未完成部分创建新任务。原任务引用作为历史保留并标明替代关系。无法确认旧成员是否继续写入时先解决归属，不能在同路径重复开工。
-
-读取状态不会自动重验。验证回执未知时先检查 job/日志；证据确实丢失且无法支撑必需结论时才补验。正文已经改而 state 未登记时先核对差异，登记后再推进；不要回滚用户文件来迎合旧状态。
-
-done 必须有当前有效验收及无阻断；缺必需环境只能报告“已实现，验证未完成”。知识处理可以是“无稳定知识变化”，不强制制造总结文档。
-
-## 13. 包结构与实现范围
-
-```text
-package.json / cordis.patch.yml / index.js
-src/tool.js
-src/state.js
-src/store.js
-src/schema.js
-skills/dev-workflow/SKILL.md
-skills/dev-workflow/references/{intent,spec,plan,execute,recover,delegation}.md
-locale/{en,zh}.json / icon.svg
-tests/{registration,state,store,resources}.test.js
-tests/scenarios.md
-```
-
-ESM JavaScript，采用 node:test；无需前端或转译器。schema 模块提供工具输入输出与状态验证，选用宿主兼容的现成 schema 能力，不能自己实现一套通用 schema 解释器。
-
-Host 注入 skills/tools/fs/workingDirectory，并在沙箱文件 backend 下要求 sandboxPolicy；直接使用的宿主依赖按核对版本声明。包名建议 dsh-dev-workflow，开发期 private，版本 0.1.0；license 和公开分发在发布前确定，不阻塞设计。打包范围明确包含 src、入口、patch、skill 参考、locale 和 icon。
-
-实施顺序：状态领域与 schema → 文件仓储与工具边界 → skill 和阶段参考 → 包注册与文档 → 集成及真实场景验收。状态模块先实现并测试，不先搭空 hook 框架。安装测试环境需授权，不将设计确认解释为 profile 安装授权。
-
-## 14. 验收方案
-
-| 层次 | 核心检查 |
-|---|---|
-| 状态单测 | 阶段约束、确认复用/撤回、同回合多决定、版本依赖、验收引用、局部失效、close 阻断 |
-| 存储测试 | 创建冲突、两次并发更新仅一次成功、正文未登记、JSON 损坏、未知版本、路径逃逸、写入失败保持旧状态 |
-| 恢复测试 | 正文已改但登记未完成、状态已提交但回执丢失、原生任务不可达、非法或缺失 state 不自动重建 |
-| 注册与包 | skill/tool 注册及清理、缺资源失败、输出 schema、真实打包资源完整 |
-| 宿主集成 | 正确 cwd/scope/sandbox；skill 可发现及加载；tool 按权限读写；停用后移除本插件贡献 |
-| 真实模型场景 | 四类提案场景，以及只设计、确认复用、Team 协作、中断恢复、浏览器缺失等变体 |
-
-四类核心场景：增量顺序交付；实现满足 spec 但 intent 不足；多轮 intent/spec/plan 变化；从空项目到真实 MVP 闭环。确认前无业务实现、无需重复确认、局部返修和有效证据复用必须在会话行为中观察，静态测试不能替代。
-
-记录具体失败与阻断、交付通过情况，以及可得的 Lead/成员总耗时与 token；指标不可得则明确缺失，不引入私有日志解析依赖。不因成本目标降低验收要求。
-
-## 15. Agent 角色与 preset
-
-调查依据见 [Agent 预设调查](research/agent-presets.md)。用户已认可首版提供 implementer、reviewer、verifier 三种按需角色指引，放在 delegation 参考中；不为每个成员角色注册独立 DSH Agent preset。这与将整套流程提供为一个开发模式不冲突。
-
-Lead 使用当前 Agent，持有流程和状态写入职责。implementer 完成明确工作包；reviewer 针对实质风险独立审查，默认不改文件；verifier 实际检查验收并提供证据，默认不改产品代码。角色不对应强制阶段，小任务仍可由 Lead 完成，不预建固定 Team。
-
-当前 Team spawn_teammate 没有逐成员 preset 参数。普通 subagent 可在宿主配置允许且 provider 支持时选择 preset，但本会话未暴露该参数；不能假设 fork 能独立换能力配置。角色指引由 Lead 连同范围、材料版本、验收、写入范围、停止条件和输出要求传入原生成员 prompt。
-
-角色提示不是权限隔离；真正只读或专用工具集需求出现时，再设计可选原生 preset 和宿主接入。首版不修改用户默认 preset、不固定模型厂商、不另建成员创建工具。
-
-## 16. 可选开发模式
-
-详细证据和取舍见 [开发模式调查](research/development-mode.md)。用户已接受：在核心之后交付一个可选的 dev-workflow preset，显示名“开发工作流”。
-
-模式复用同一 skill/状态工具，增加短入口提示和经过验证的原生能力组合；核心仍可在其他兼容模式使用。利用原生新会话模式选择器，不新增 UI。模式选择不等于实施授权，不创建 change 或预启动成员；受委派成员遵循任务包，不重复进入 Lead 流程。
-
-首个验证组合包含文件/搜索/shell/jobs、skill、用户交互、历史查询与 Team 协作；普通 subagent 仅在实际部署提供时使用。浏览器、记忆及其他集成为按需能力。模型、权限、账号和默认模式保持用户配置。
-
-PresetDefinition 没有直接 extends 字段；不复制整份基础 profile，也不动态修改用户 Standard 模式。采用显式有界声明复用宿主能力，必要的模式贡献在正确 scope 注册；提供服务的子配置必须正确 isolate。全局工具可能仍可见，不宣称 preset 天然隔离工具或权限。
-
-模式仅能在会话首轮前选择。运行中通过核心 skill 使用流程，或新建开发会话恢复既有 change。注册/安装与会话选择分开，不能自动设置为默认或切换现有会话。核心与模式适配入口同仓库分离，先不拆多个包。
-
-增加的验收重点是：实际工具视图、无服务泄漏或重复注册、普通模式不受影响、成员继承和职责正确、只设计请求不越界，以及升级/停用/恢复的实际行为。不在没有运行证据时承诺降低 token 或提高成功率。
-
-## 17. 当前设计状态
-
-架构、目录、状态工具、版本契约、按需角色指引及可选开发模式均已获用户认可。没有阻塞首版实施的产品或架构选择需要用户补充。
-
-剩余工作分为：实现时确定并测试具体 schema、包入口和 preset 配置；通过宿主集成验证 scope、文件策略、实际工具视图、成员继承及升级/恢复；发布前确定 license 和公开分发方式。后续 hook 事件映射不属于首版。技术验证如推翻已确认边界，再报告具体影响，不为常规实现细节重复审批。
-
-首版实施已获授权，具体工具字段以 src/schema.js 为准。实现补充：bind-step 可在提供 reason 后替代原绑定，previousBindings 保留原生任务来源；材料目录/文件拒绝符号链接；可选 preset 显式要求部署提供必要原生能力，缺失时报告配置问题。未修改用户 profile 或默认模式。
-
-## 18. 开发中的分支扩展
-
-完整契约见 [分支与 worktree 隔离设计](branch-management.md)，模型使用规则见 [工作区参考](../skills/dev-workflow/references/workspace.md)。扩展保留既有阶段、授权和验收状态机，增加当前工作区观察及状态写入绑定，不增加调度器。
-
-- 独立需求默认独立 change、分支、worktree 和 Lead。外部助手负责 Issue 领取、分配、准备 worktree 和启动会话；同一需求内仍用原生 Teams。代码、知识、change 和需保留的证据全部位于本 worktree，知识来自基准提交快照，不共享材料根或实时读取其他 checkout。
-- action 增加只读 workspace；每个 action 顶层 workspace 按实际 cwd/projectRoot 直接返回实时工作区，无 current/status 嵌套。workspace action 无 bindingStatus；get 顶层 bindingStatus 仅为 matched/mismatch/detached，binding 为已存绑定；list 有效行 workspace 为已存绑定并附 bindingStatus，未受管目录显示缺失或非法 state 错误。Git 项目根与 cwd 须属同一 checkout，普通目录根须在 cwd 内。detached 只读，unborn 命名分支允许使用，bare 拒绝；Git、宿主、权限、取消或损坏错误不降级成普通目录。
-- 状态格式仅接受 schemaVersion: 2，workspace 必填，Git 绑定为 `{ kind: 'git', branch, baseCommit, projectPath }`，普通目录为 `{ kind: 'directory' }`。未知或旧 schema、缺失绑定拒绝，不自动转换或修复。baseCommit 可为 null，只记绑定来源，不做 HEAD 相等或祖先检查；不持久化机器绝对路径、session owner 或可变当前 HEAD。
-- 分支改名、已有明确接管依据或普通目录初始化为仓库后，单独 update/bind-workspace，仅提供 reason 和当前 expectedRevision，不夹带业务操作。重绑通过 CAS 更新，workspaceHistory 每项的 previous、reason、recordedAt 必填；不能用来修复缺失绑定或非法 schema。相同绑定不增加 revision，普通提交/rebase 不刷新原 baseCommit。mismatch 拒绝普通写；合入历史不自动改归属。
-- 绑定只保护状态工具的写入，不充当 Git 锁或 Lead 所有权锁。运行期间不得外部切分支、搬移或清理 worktree；正文与其他文件工具同样须遵守工作区约定。计划和委派包包含本 worktree 的 projectRoot、changeId、预期分支及工作目录，恢复先核对工作区与绑定。
-- PR/MR 地址、源/目标分支、评审/合入结果和证据沿用 plan/交付材料。合入是否为 close 前提由需求验收决定；PR 反馈沿用阶段退回、版本与证据失效机制。知识/state 冲突需要语义核对，文本合并不等于验收；提交和清理仍需对应授权。端口、数据库、账号等资源按需求另行隔离。
-
-扩展的程序验证和真实行为观察分开记录在 [场景记录](../tests/scenarios.md)；首版通过记录不构成扩展已通过的证据。

package/docs/proposal.md

@@ -1,129 +0,0 @@
-# DSH 原生开发工作流提案
-
-日期：2026-11-06
-状态：讨论稿 v0.4；明确独立 intent、人的需求与方案审核、轻量材料边界。
-项目暂名：dsh-dev-workflow。
-
-## 提案的范围
-
-本提案说明工作流应做什么、经过哪些节点、人与 AI 如何参与，以及需要保存哪些材料。它是整体框架和执行流程，不是完整实现设计。
-
-具体字段、schema、状态枚举、工具 API、存储算法和校验脚本留到实现需要时再确定，不作为提案完成的前置条件。当前仍在设计讨论，尚未开始插件实现。
-
-## 目标与边界
-
-- 独立仓库、独立发布，面向 DSH 原生实现，充分复用 Agent Teams。
-- 覆盖从真实需求识别、方案设计到实施验证的完整过程，支持增量开发和新项目 MVP。
-- 人主要参与意图识别和框架方案设计；AI 负责调查、整理、实施规划、执行与验证。
-- 需求与方案必须经过人的判断，不能仅因 AI 认为信息充分就直接进入实施。
-- 文档和知识体系保持轻量；按需读取，避免重复记录、重复探索和无限验证。
-- 验证按任务需要配置。BrowserSkill 可选且可替换，不是必需依赖。
-- 本版交付到经过验证的开发结果与说明，不包含自动提交、推送、发布。插件自身的分发方式另行考虑。
-
-现有 Nuclio 的轻量工作流与知识组织值得保留；本项目主要解决 DSH 原生协作适配、流程边界与上下文效率问题，不以增加治理层和文档层为目标。[LabWarden 案例](research/labwarden-session-cost.md)说明，大截图矩阵、重复读取和无效压缩可能放大成本；工作流优化需观察整个团队，而非只减少主会话的 compact。
-
-## 主链路与人的参与
-
-```text
-用户提出需求（可以只有一句话）
-    ↓
-意图识别与澄清 ↔ 用户补充背景、纠正理解
-    ↓
-形成 intent：真实需求由用户确认
-    ↓
-方案与 spec 设计 ↔ 用户评审框架方案、关键取舍
-    ↓
-用户确认：这个方案符合预期，可以据此实施
-    ↓
-生成 plan
-    ↓
-执行 plan ↔ 验证与局部返修
-    ↓
-交付结果与必要知识整理
-```
-
-意图确认与方案审核是明确的人参与节点。简单需求可以在一次交流中一起确认，复杂需求可以分别往返讨论；不机械要求固定轮数，但不能省去用户判断。用户已明确确认相同需求与方案时，直接沿用，不因阶段切换或恢复再审批一次。
-
-方案审核前，AI 应完成必要调查并形成可评审的具体方案。审核要让用户能判断预期结果、影响范围、整体实现思路及重要取舍，而不是只问“是否继续”。用户拥有模型未必掌握的业务背景、外部约束和经验，这次审核本身具有价值，不只是权限检查。
-
-plan 负责落实已确认方案，默认由 AI 生成和执行，不另设固定人工审批。不能把应由人评审的框架选择藏到 plan 中。阶段名称也不等于宿主 Plan Mode。
-
-## intent、spec、plan 的分工
-
-| 材料 | 回答的问题 | 应保存的内容层次 |
-|---|---|---|
-| `intent.md` | 用户真正需要什么，为什么？ | 原始诉求、经澄清的真实需求、背景与目标、范围和重要约束 |
-| `spec.md` | 用什么方案实现 intent，结果应是什么样？ | 可供人审核的框架方案、关键取舍、预期行为和必要验收要求 |
-| `plan.md` | 如何把已确认方案做出来并验证？ | 实施步骤、工作分工、必要依赖和验证安排 |
-
-intent 独立保存，不能只作为 spec 中顺带描述的目标段落。它不是机械复述用户原话，也不能把 AI 的推测直接当成真实需求。意图识别结合定向调查和与用户沟通，发现一句话背后的场景与诉求，并由用户校正。
-
-例如，“不要再让我填 ID”可能表达的是“让我能可靠找到并选中目标对象”。intent 保存这个需求；spec 决定名称检索、同名区分和稳定 ID 绑定等解决方式；plan 决定相关接口、控件与验证如何实施。方案可以变化，需求仍能独立回看。
-
-三份材料按任务规模写，简单任务每份可以只有几行，不设置篇幅、章节数量或字段填满要求。spec 不复制 intent 全文，plan 不复制 spec；已有项目知识以引用为主。人的确认和关键决定就近简记，不新增审批表、决策账本或每阶段报告。
-
-## 四类必需场景
-
-| 场景 | 流程要求 |
-|---|---|
-| 增量需求，一次依次完成 | 澄清并确认 intent，设计并审核方案，AI 生成 plan 后实施验证 |
-| 实施验证后发现意图不足 | 回到 intent，与用户重新对齐真实需求，修正方案；新的需求/方案决定明确后继续受影响工作 |
-| 意图、方案或 plan 多次变化，实施可能循环 | 允许往返，按问题所在层调整；保留仍有效的成果，避免每轮全量重走 |
-| 新项目初始化 MVP | 与用户明确最小用户闭环和非目标，审核框架方案；按可运行的功能切片实施，直到核心流程得到验证 |
-
-新项目不建立第二套工作流。先跑通一条真实用户流程，再完善 MVP 必需能力；脚手架、构建成功和演示数据不等于 MVP 完成。增量需求则复用现有结构和知识，保护已有无关改动，不强制新建分支或清空工作区。
-
-## 调整与回退
-
-| 问题 | 调整方式 | 人是否参与 |
-|---|---|---|
-| 实现不符合已确认 spec | 局部修代码并验证 | AI 自主返修 |
-| 实施顺序、分工或技术细节不合适 | 调整 plan | AI 自主处理，不改变已确认方案 |
-| 框架方案不可行或重要取舍需要变化 | 修订 spec，说明差异与影响 | 用户审核改变的方案 |
-| 结果符合 spec，却没有满足真实需求 | 重新澄清 intent，再修订 spec/plan | 用户参与需求和方案对齐 |
-| 用户提出新的独立需求 | 明确当前工作与新增工作的边界 | 用户确认需求/方案，不悄悄扩展范围 |
-| 验证工具或环境出问题 | 排查环境或选择能证明同一结果的方式 | 通常由 AI 处理；确需用户提供条件时说明缺口 |
-
-用户的直接纠正若已把需求与方案说清楚，应作为当前决定使用，不再原样询问。发生变化时只评审必要差异，不重新审批整个历史。
-
-一般执行不依赖用户逐步监督。用户仍可随时提供反馈；涉及额外权限、外部副作用等特殊情况沿用宿主与用户已有授权规则，不另造权限系统。
-
-## 验证、收敛与恢复
-
-- plan 包含与改动相称的验证安排；实施过程中就近验证，最后做必要集成检查。验证同时对照 spec 和 intent，避免实现正确却需求错误。
-- 项目已有静态检查、测试、构建、API/CLI 或浏览器工具按需选择。替代方式应证明同一结果，不能用编译成功替代交互通过。
-- 留下简短验证结果和必要原始依据引用；工具成功不等于业务通过，截图生成不等于实际查看，fixture 不等于真实集成。
-- 返修后重验受影响部分及必要回归。未变化、仍适用的结果继续使用；compact 或任务重排不自动触发全部重验。
-- 同一问题反复失败时，先改变诊断或执行方法，不能靠原样重试、反复读图、不断创建代理消耗上下文。预算用于提醒调整方法，不用于降低验收标准。
-- 已满足确认的需求与规格、必需验证通过且没有未解决阻断，就结束当前交付。新增想法不自动扩大当前范围。
-- 恢复读取当前 intent、spec、plan、必要进度及验证结果，核对实际产物后继续。无需重演完整对话或重读全部材料。
-
-具体如何标识版本、判定证据失效和存储恢复状态，在实现时选择足够简单的办法；提案不预设完整证据管理系统。
-
-## 轻量知识与材料保存
-
-单次工作的主要材料是 intent、spec、plan。另保留足够继续工作的简短进度、验证结论及引用，可附于现有材料或使用原生记录，不规定额外成套文档。完整日志与大截图不搬进这些文件。
-
-项目长期知识与单次需求分开，沿用轻量组织原则：
-
-- 一个简短入口，指向少量实际有用的项目知识；不预建复杂分类和空目录。
-- 按当前问题读取相关部分，不要求每个阶段遍历整套知识。
-- 复用已有 README、架构和运行说明，不平行维护同内容副本。
-- 完成工作时只更新真正改变的稳定事实和已失效说明；无新知识就不制造总结文档。
-- 临时假设、调试过程和任务进度不沉淀为长期知识。
-
-提案确定这些内容需要保存，但不展开完整目录模板、字段规范、数据库设计或强制归档流程。优先使用人可读的项目文件；原生会话和任务记录已有的信息尽量引用。具体位置在实现时以易读、易恢复、少重复为准。
-
-## DSH 原生协作边界
-
-Lead 负责与用户对齐 intent/方案、组织实施、集成和交付。复杂任务使用 Agent Teams；有界独立调查可用 subagent；小任务直接完成，不固定角色数量。
-
-Team 承担任务、依赖和成员状态；plan 保留实施思路和任务引用，不复制第二张可写任务板。共享写入明确归属与交接。成员停止活动、任务完成和交付通过是不同事实，不能相互替代。
-
-复用 DSH 已有调度、权限、压缩与界面能力；不重做 DAG、任务引擎、压缩引擎或浏览器引擎。细节按阶段加载，大输出保留引用和有界片段。具体宿主 API 在实现前核对，不假设跨会话原成员一定可恢复。
-
-## 首版评估与后续工作
-
-用四类场景评估：需求是否识别正确、方案是否经过人审核、AI 能否按方案自主完成、返修是否局部收敛、新项目是否真正可用。结合中断恢复、可选浏览器和原生协作，观察漏验、重复劳动、Lead 与成员总成本及交付成功率，不单看 compact 次数。
-
-流程层面以本提案为准。接下来可检查是否还有缺失的必需节点，再进入最小实现设计；不必先把所有字段、边界和恢复协议讨论完。早期详细[行为合同草稿](workflow-contract.md)仅作为历史设计参考，其中弱化方案人工审核、合并 intent 的内容已被本提案取代，不作为首版必读文档或实施清单。

package/docs/research/agent-presets.md

@@ -1,99 +0,0 @@
-# 是否需要预设 Agent
-
-日期：2026-11-07。调查基线：本机 DSH 0.2.2-rc.1 的安装代码和本会话工具 schema。结论来自静态接口及调用链核对，没有创建测试成员、修改 profile 或安装插件。
-
-## 结论
-
-本文结论针对“按成员角色分别预设 Agent”：首版应提供可复用的角色指引，不为每个角色注册一个 DSH Agent preset。将整套开发流程组合为一个可选模式，是另一层设计，见[开发模式调查](development-mode.md)。Lead 继续使用用户当前 Agent，按任务需要选用 implementer、reviewer、verifier 三种职责，将对应指引和具体任务一起交给原生 subagent 或 Team 成员。角色不是必经阶段，不要求每次启动三个成员。
-
-这里区分三件事：
-
-- 角色指引：工作职责、输入、边界、完成标准和结果格式。
-- 原生 Agent preset：由 Cordis 子插件组成的能力配置，可能改变工具和服务。
-- 模型路由：provider/model/reasoning effort 等选择；不是给成员起角色名就会改变。
-
-首版的实际需求主要是稳定分工和交付质量，角色指引已足够。若未来确实需要不同的工具集、权限或上下文能力，再增加原生 preset；不能把“只读 reviewer”提示词描述为权限隔离。
-
-## 宿主证据
-
-安装代码根目录为 `/home/fooksky/.local/share/fnm/node-versions/v26.13.0/installation/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/`。以下路径以该目录为基准，方便在其他安装位置重复调查。
-
-| 证据位置 | 已核对事实 | 设计影响 |
-|---|---|---|
-| dsh-agent-preset-registry/lib/types/definition.d.ts:4 | PresetDefinition 是 id/name/description/order/plugins | 原生 preset 是能力组合，不只是角色提示词 |
-| dsh-agent-preset-registry/lib/types/index.d.ts:52 | register 返回异步 disposer | 自建 preset 需要管理注册及生命周期 |
-| 同文件:99–132 | mount、composeFrom、select；子 Agent 可继承父 preset 的确切 revision；select 仅适用于首轮前 | 不能在正在运行的成员上随意切换角色 preset |
-| dsh-experimental-tool-agent-team/lib/index.js:251–289 | spawn_teammate 参数仅 name/description/prompt/context；fresh/fork provider 来自工具配置 | 当前公开 Team 工具无法逐成员指定 preset 或模型 |
-| dsh-experimental-agent-team/lib/index.js:1035–1045 | 成员 activation 传 provider、prompt、parent，没有逐成员 agentPreset | 不能只在技能里写一个 preset 名就认为 Team 会选用它 |
-| dsh-tool-subagent/lib/index.js:243–281 | agentPreset/allowedAgentPresets 配置；按 allowlist 暴露 agent_preset；provider 必须支持独立 preset 且不继承上下文 | fresh subagent 可有条件支持；不能无条件套用于 fork |
-| 本会话 subagent schema | 有 provider/model/reasoning_effort，没有 agent_preset | 当前会话不能直接测试按 preset 委派 |
-
-这些发现不代表宿主永远不支持 Team preset，只代表当前公开链路没有该选择入口。为首版改造 Team 或绕过原生工具创建成员，会扩大范围并引入第二条执行路径。
-
-## 角色设计
-
-### Lead：当前会话承担
-
-负责真实需求、方案取舍、用户确认、主文档、状态更新、任务拆分、整合与交付。不能把语义决策和授权判定委托给一个自动推进的角色。Lead 不需要新增 preset，已有 dev-workflow skill 提供流程规则。
-
-### implementer：实现或修复工作包
-
-输入：具体任务、已批准范围、相关 spec/plan 段落、验收 ID、允许写入的范围和必要上下文。
-
-职责：完成有界实现及与之相关的检查，报告修改与证据；发现范围或方案不成立时停止受影响工作并报告，不自行扩大需求。
-
-输出：完成情况、修改路径、相关验收、已执行验证及结果、未验证项、阻断。不能代替 Lead 更新主材料或登记用户授权。
-
-小任务由 Lead 自己实现；只有可独立交付或并行收益明确时才委派。按文件/模块工作包分工，不固定前端、后端、数据库等常驻岗位。
-
-### reviewer：独立审查
-
-输入：需要回答的审查问题、明确差异或方案范围、相关验收、必要上下文。
-
-职责：发现可说明触发条件和影响的实质问题，优先正确性、契约不一致、集成遗漏与需求偏差。没有问题时直接说明，不为凑数给风格建议。
-
-输出：结论；每个问题的具体位置、触发条件、影响、依据及必要修正方向；未覆盖边界。默认不修改文件，修复另行明确分派。
-
-在跨模块契约变化、重要迁移、复杂并发或容易自证的变更中使用。低风险局部修改不要求独立审查；不固定多评审轮数。fresh 上下文适合独立判断，但仍需提供足够约束，不能靠上下文缺失制造“独立”。
-
-### verifier：验证与证据收集
-
-输入：验收 ID 与对应行为、被测对象、环境、验证方法、现有证据及缺口。
-
-职责：实际检查验收命题，区分通过、失败和无法验证。浏览器、CLI、测试工具按当前可用能力选择；缺环境报告阻断，不生成假证据。默认不改产品代码，避免边修边验掩盖测试对象变化。
-
-输出：每项验收的观察、方法、被测版本/产物、环境、证据位置、未覆盖项及失败复现。结果是给 Lead 的证据报告，最终验收状态仍由 Lead 登记。
-
-复杂 UI、外部集成或需要独立端到端检查时单独委派。简单任务由实现者或 Lead 验证。批量视觉检查按有界工作包分配，保持完整覆盖并避免重复读图。
-
-## 指引的装配方式
-
-新增一份按需读取的 skill 参考 `references/delegation.md`，包含三段角色契约和一个委派模板，不增加三个独立 skill 或三套全量系统提示。
-
-Lead 发送的实际 prompt 必须自足，包含：
-
-1. 角色职责及本次具体问题/目标。
-2. projectRoot、changeId、任务 ID（Team 场景）、相关 A/P 编号及关键材料版本。
-3. 必要资料位置和足以开工的摘要；fresh 成员不能只收到“按上文做”。
-4. 允许写入范围、禁止触碰的主材料、依赖和已知并行成员。
-5. 验证要求、停止/反馈条件、结果格式。
-
-不要求成员读取整个技能或全量历史。角色规则写入成员任务提示；会改变的长说明通过明确路径引用。主流程规则只由 Lead 持有，避免子成员再次发起完整需求确认或重复组织 Team。
-
-需要持续交流、任务领取和多轮修复时使用 Teams；一次性调查或审查用普通 subagent；需要继承历史时才 fork。成员命名描述当前工作，如 storage-impl、api-review，而不是预建固定组织架构。
-
-模型选择继续使用宿主现有配置。首版不指定模型厂商或固定“高级 reviewer/低价 implementer”映射。角色质量应通过真实结果和成本评价，不能从模型名称推定。
-
-## 何时再引入原生 preset
-
-出现以下实际需求时再单独设计：验证角色需稳定的浏览器能力组合；审查角色需宿主可执行的只读限制；某个专用工具集过大，需要隔离以降低上下文成本。
-
-届时先核对可用 provider 的能力及宿主选择入口，决定是否只用于 fresh subagent；若必须用于 Team，则先扩展宿主公开契约。不能在本插件中另写成员管理器补洞。工具不暴露并不自动等于只读：shell、连接器等也可能写入，真正权限必须由宿主策略保证。
-
-原生 preset 的分发是可选独立配置，不改变用户默认 preset、不自动切换已有会话、不在安装时静默替换工具组。
-
-## 验收与取舍
-
-在原有四类提案场景中检查：小任务不强制委派；fresh 成员可凭任务包开工；reviewer 指出可复现的实质问题或明确无发现；verifier 区分已观察和推测；成员不写主状态；修复后只重验受影响项。
-
-比较直接执行和按需角色委派的缺陷发现、验收完成、重复读取和总成本。在没有实际收益证据前，不追加 researcher、architect、planner、knowledge-writer 等常驻角色。