@netpilot/skills 0.3.2 → 0.4.0

package/docs/agent-authoring.md

@@ -5,11 +5,11 @@
 ## 职责边界
 
 - Agent：保存一个窄角色的关注点、权限边界、证据要求和固定返回格式。
-- Skill：保存触发条件、完整工作流、降级路径、验证与完成标准。
+- Skill：保存触发条件、上游方法本身的步骤或参考结构、降级路径与必要验证；只在真实步骤边界保留 completion criterion，不统一追加尾部模板。
 - 项目 `AGENTS.md` 与 standards：保存业务事实、架构约束、安全红线和项目命令。
 - 主 agent：拆解任务、选择子代理、限制写入范围、整合结论并承担最终判断。
 
-Agent 不应成为完整工作流、项目规范副本或长期人格。实现工作优先使用 Codex 内置 `worker`，代码定位优先使用内置 `explorer` 或本项目的窄职责 `code-reader`。
+Agent 不应成为完整工作流、项目规范副本或长期人格。实现工作使用 Codex 内置 `worker`，代码定位使用内置 `explorer`；只有职责、工具面或安全策略确实不同才新增 custom agent。
 
 ## 配置约定
 
@@ -25,10 +25,10 @@ Agent 不应成为完整工作流、项目规范副本或长期人格。实现
 
 ## 权限与模型强度
 
-- reviewer、reader、designer 默认 `read-only`，指令正文同时明确禁止写入。
+- reviewer、designer 默认 `read-only`，指令正文同时明确禁止写入。
 - verifier 只有在测试工具会产生缓存或构建产物时才使用 `workspace-write`；必须禁止修改受版本控制文件、安装依赖和更新快照。
 - 分发 Agent 禁止 `danger-full-access`。
-- 直接代码定位使用 `low`；测试执行通常使用 `medium`；架构、安全、并发和数据一致性审查使用 `high`。
+- 普通代码定位交给内置 `explorer`；测试执行通常使用 `medium`；架构、安全、并发和数据一致性审查使用 `high`。
 - sandbox 是默认值，父任务的实时权限可能覆盖它，因此行为限制不能只依赖 TOML。
 
 ## 新增门禁
@@ -46,12 +46,22 @@ Agent 不应成为完整工作流、项目规范副本或长期人格。实现
 
 ## 返回契约
 
-只读 Agent 返回事实、可定位证据、推断、未知项和建议下一步；Reviewer 按严重度返回可触发 finding；Verifier 返回实际命令、退出码、关键输出、未执行项和环境限制。不得把建议写成已经验证的结论。
+只读 Agent 返回事实、可定位证据、推断、未知项和建议下一步。Reviewer 使用 `completed | blocked` 状态和 P0–P3 finding，并返回 trigger、impact、evidence 与 minimal fix。Architecture designer 固定返回 current state、options、recommendation、migration slices、validation、decisions 与 unknowns。Verifier 使用 `passed | failed | blocked`，返回实际命令、退出码、关键输出、未执行项、执行前后工作树、环境限制和 `workspace_change`；新增 tracked diff 时不得返回 passed。不得把建议写成已经验证的结论。
 
 ## 双宿主策略
 
 Skills 保持 Codex 与 Claude Code 共用单源。Agent 配置是宿主专用适配，不强求两种宿主使用相同格式、模型名或权限语义。真正支持 Claude Code Agent 时，在独立宿主目录中实现并建立能力映射，不复制 Skill 工作流。
 
+## 工具与第三方 API
+
+Codex custom agent 可以声明 `mcp_servers`，未声明时也会继承父任务已经配置的工具。NetPilot 的可分发用户 Agent 刻意不内置 MCP server、endpoint 或凭据：它们跨项目安装，无法安全假定某个组织的平台、账号和权限；需要文档、GitHub、浏览器或其他 API 时，使用当前任务已经配置且获准的工具。
+
+- 只读 reviewer 和 designer 只允许查询与取证，不因工具已连接而获得外部写权限。
+- `test-verifier` 只运行项目允许的验证命令，不 dispatch workflow、发布制品或部署。
+- secret 由宿主或受管平台注入，不写入 Agent TOML、项目文件、提示、日志或快照。
+- 外部 mutation 必须由项目级流程处理，并具备精确目标、当前任务授权、最小 RBAC、短期凭据、幂等、并发控制、审计和回滚。
+- 需要专用工具面的 Agent 应由项目层定义；可分发 Agent 保持窄职责并继承当前会话，不提供通用 shell 或生产系统旁路。
+
 ## 验证
 
 提交前运行：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netpilot/skills",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "面向 Codex 与 Claude Code 的中文工程协作 skills 与可选 Codex agents",
   "keywords": [
     "codex",