Agent 工作方式与适用边界

核心概念：任务闭环

chatbox 的默认形态是问答：你问一句，它回一段。coding agent 的默认形态是任务闭环：它可以读代码、改文件、跑命令、看结果、再继续修正。你不再只是问它“怎么做”，而是把一个边界清楚的目标交给它推进。

这也意味着你要从“写提示词”切换到“管理一个协作者”：交代目标、给上下文、设边界、审计划、看验证证据、决定是否接受改动。

• 任务输入：目标、上下文、约束、验收标准。
• 执行过程：先读、先计划、最小改动、按证据验证。
• 人类职责：批准边界、处理取舍、审查风险、决定是否合并。
• 沉淀方式：把重复纠正变成规则、命令、Skill 或 Hook。

第一类任务要足够可控

第一次不要直接交给它一个跨模块大改。先选一个能从 git diff 和命令结果判断质量的小任务，观察它是否会读上下文、是否会越界、是否会偷懒验证。

• 边界清楚：只改一个页面、一段逻辑、一个脚本或一组同构文件。
• 风险低：不碰支付、登录、权限、生产数据迁移、secrets 和基础设施。
• 能验证：可以跑 lint、测试、构建，或用浏览器看到结果。
• 可回滚：动手前工作区干净，改坏后能从 git diff 退回。
• 可复盘：结束后能判断这类任务以后是否值得沉淀。

请只修改 /manual/agent 相关手册内容，让“agent 不是 chatbox”这一段更具体。不要改布局、样式、路由和导航。完成后运行 npm run lint，并说明改了哪些段落、哪些页面没有验证。

请阅读 scripts/new-writing.mjs，只调整缺少 title 时的错误提示，让它更明确。不要改变创建文件逻辑。完成后运行最小命令验证错误提示。

按任务类型切换协作方式

• 探索任务：只读，要求梳理结构、列方案和风险，不改文件。
• 实现任务：给清楚目标、范围、接口约定和验收方式。
• Bug 修复：给复现路径、错误日志和期望行为，要求先定位根因。
• 重构任务：强调行为不变，并要求用测试或等价检查证明不变。
• 发布检查：重点查入口、构建、元数据、文档、回滚方式和 CI 状态。

目标：修复登录过期后请求全部 401 的问题。
上下文：复现路径是登录后等待 session 过期，再刷新页面并触发任意接口请求。
要求：先只读地检查 auth/session/token refresh 相关代码和测试，说明当前流程、最可能根因、最小复现方式。确认根因前不要改代码。
验收：能用同一路径复现并确认修复；如果项目有相关测试，补或更新最窄测试；最后运行相关检查。

什么时候不该让它自由发挥

不该用 agent 的场景，很多时候不是“不能用”，而是不能让它自己决定边界。你可以让它调研、列方案、写风险清单，但最终原则和取舍要由人给。

• 产品方向、商业取舍、隐私边界和安全策略：先由人给原则。
• 生产数据迁移、支付、权限模型和 secrets 处理：必须先有设计、审批和回滚方案。
• 目标不清的需求：先让它采访你或做探索，不要直接实现。
• 高影响面重构：先做影响面分析和验证计划，再小步推进。
• 不可逆命令：永远先问必要性、范围和恢复方式。

先识别跑偏信号

• 幻觉上下文：说出不存在的文件、命令或测试。要求它用真实路径重新证明。
• 过度执行：只改文案却开始改组件、路由或样式。立即收窄到原始验收标准。
• 验证偷懒：没有跑命令却说通过。要求区分已验证、推断和未验证。
• 权限膨胀：普通任务突然要求安装依赖、联网、删除文件或跨目录写入。先问必要性和替代方案。
• 反复纠正无效：同一问题纠正两次还不对，清空上下文，用更精确 prompt 重来。

照着做

在当前项目里找一个低风险的小改进点。先说明你准备改哪里、为什么、风险在哪里、怎么验证。得到我确认后只做最小改动；完成后运行最接近的检查，并汇报改动、验证和未覆盖风险。