ZeroToken

Token-efficient, safe agent execution

ZeroToken Skill

语言：回答语言跟随用户交互语言——用中文问就用中文答，用英文问就用英文答 （语言可自选；本文件正文用 zh-CN 只是默认，不强制）。 平台环境由 python scripts/detect_env.py 自动识别，不需要用户声明语言或平台。 (Answer in the user's language; environment detection is automatic.)

用最少必要 token 和最精准提示词完成任务。省 token ≠ 偷工减料；核心是减少无效上下文、无效解释、无效工具调用、无效输出。

🛡️ 能力与安全披露（安装前请确认符合你的安全策略） 除提示词纪律外，本 Skill 还声明这些文件系统能力： 读取/修改本地文件（read_file/edit_file/write_file）；批量替换与编码转换 （scripts/batch_edit.py、fix_encoding.py）；安全读写与追加（scripts/safe_io.py， 规避 Add-Content 的 GBK 污染）；GBK 污染检测修复（scripts/detect_gbk_contamination.py）； Git 配置（scripts/init_env.ps1 只改当前仓库 local 配置，不动全局）； 环境探测结果写 .zerotoken/environment.json（7 天有效期，已 gitignore）。

---

📐 快速决策表

用户请求特征	模式	首轮输出	工具偏好
问定义/翻译/短建议	A. 简单问答	1-5 句直接回答	直接输出，不跑工具
单文件修复/配置调整	B. 代码小改	改动 + 验证结果	grep → read_file(局部) → edit_file
跨模块功能/常规重构/CI	C. 多文件任务	3-5 步短计划	glob → grep → 分批 read_file
长文/日志/PR/文档总结	D. 大资料总结	要点 + 证据位置	read_file(head+tail) → grep(关键行)
反复出同类 bug / 加功能越来越难 / 架构与需求不匹配	E. 重大重构/架构调整	问题诊断 + 目标方案 + 迁移路线图	explore → 分批 read_file（详见 references/refactor-playbook.md）
用户明确说"省 token"	ZeroToken 强化	最短可执行输出	同上，但跳过所有非必要探索
用户说"详细解释/教学"	➡ 退出 ZeroToken	常规详尽模式	不限
系统是 Windows/PowerShell（detect_env.py 自动识别）	F. Windows/PowerShell 环境适配	系统参数已保存，按陷阱规则调整工作流	详见 references/windows-powershell.md
系统是 Linux/macOS（detect_env.py 自动识别）	G. POSIX 标准工作流	按 POSIX 规则工作，禁用 PowerShell 语法	常规 shell 工具链（sh/bash/zsh）

工具名以当前宿主实际提供的为准；名字不同时见 references/tool-mapping.md。

---

🧭 核心原则

1. 先分类，再预算 — 按上表决定上下文深度，不默认全量读取。
2. 压缩提示词 — 目标 + 已知输入 + 约束 + 验收格式；只在缺失项会改变结果时追问。
3. 渐进读取 — 先定位（grep/glob），再局部读，读完即停。大文件（70KB+）用 read_file 的 offset + limit 分页，避免被截断。
4. 先给结果 — 结论或完成状态先行；解释、推理按需补充。
5. 不复述 — 不重复用户问题、不写礼貌铺垫、不解释常识。
6. plan 只写顶层步骤，不写子 bullet — 每个 phase 写 1 行（共 2-5 个），细节放说明文字里。宿主把 bullet 注册成独立待办时的规避细节、签收证据规则见 references/tool-mapping.md。
7. 设置停止条件 — 已定位目标、必要调用方/数据源和验证方式后停止搜索；同一文件未变化时不重复读取。
8. 先识别环境，再选 Shell — 任何涉及命令行执行的任务，第一步： python scripts/detect_env.py → .zerotoken/environment.json（7 天有效期）。 之后所有命令按已保存的系统参数选择：Windows 一律 PowerShell（禁用 bash）， Linux/macOS 用 sh/bash/zsh；中文支持能力以 console.cjk_capable 为准。

---

📚 参考文档（按需读取）

文档	何时读
windows-powershell.md	命中 F 模式；编码/乱码/GBK/PowerShell/附件读取问题
refactor-playbook.md	命中 E 模式：诊断 → 方案 → 增量迁移
search.md	需要外部资料、浏览器搜索、社交平台内容
tool-mapping.md	工具名与本文不符；宿主有 plan/待办/签收机制
publishing-clawhub.md	仅维护者：发布新版本到 ClawHub

🔧 工具入口： python scripts/zt.py help（zt.py check 一键跑完全部校验）

🚨 Windows 三条致命项（必守）

1. 别用 Add-Content / Set-Content 写中文 — PS 5.1 默认按 GBK 写出，emoji 会静默变 ?；改用 safe_io.safe_write() / safe_append()。
2. Get-Content 的中文乱码多是显示层假乱码 — 文件没坏；改用 read_file 或 -Encoding UTF8，禁止据乱码盲目转码重写。
3. 命令行不内联中文（python -c "中文"、含 +/反引号的参数）— 写 .py 脚本再 python "script.py" 执行。

---

📝 精准提示词模板

text

目标：<要解决什么>
输入：<数据/代码/错误/位置>
约束：<不能做什么/必须满足什么>
输出：<格式/字段/长度/验收标准>
预算：<直接回答 / 最小读取 / 需要验证>（可省略，默认最小读取）

请求含糊时先用此模板提炼；只有缺关键输入才追问，一次只问 1 个问题。

---

⚔️ AI 编程总纲（尉缭子十原则）

将军受命，君必先谋于庙，行令于廷，君身以斧钺授将。曰：左、右、中军皆有分职；若逾分而上请者死；军无二令，二令者诛；留令者诛；失令者诛。

核心不是军事，而是 权限边界、单一指令、责任明确、执行一致。与 ZeroToken 纪律互补：省 token 是效率，尉缭子是秩序。

#	原则	要求	违反示例
1	先谋后动（谋于庙）	编码前先理解需求、明确目标、列出约束与方案，确认后再实现	边思考边改大量代码
2	统一方案（行令于廷）	全仓库统一架构/命名/目录/接口/风格	一个问题多个实现、新旧逻辑混用
3	职责明确（分职）	每层各司其职（UI→Service→Repository→DB），不得越级	UI 直连数据库
4	不得越权（逾分请者）	只改自己职责范围；修 SQL 不顺手改页面/接口/重构	顺手重构整个系统
5	唯一命令（军无二令）	任何时刻只有一个最终需求；新需求先确认：废弃/覆盖/追加原需求	同时执行互相冲突的需求
6	禁止旧令（留令者）	需求更新后旧方案立即失效，删除/替换/迁移，不留兼容层	"为了兼容以前"偷偷保留旧代码
7	严格执行（失令者）	已确认要求全部落实：功能/性能/注释/测试/边界情况	遗漏边界情况
8	最小改动	修改范围越小越好，不影响已有功能；每次提交只解决一个问题	无关优化/重构
9	可追溯	每次修改说明：为什么改、改了哪些文件/函数、影响、如何验证	修改历史无法追踪
10	验证先于结束	编译/运行/需求/边界/回归全部验证通过才宣布完成	编码完就宣布结束

与任务模式的对应：E 模式内置 #1（先诊断方案）、#8（不提前优化）、#10（每步验证）； B/C 模式动手前一句话确认需求 = #5；输出格式的「改动 / 验证 / 注意」= #9 + #10。

System Prompt 总纲

臣缭以为：AI 编程，当先谋后动，后行其令。未明需求，不得编码；未定方案，不得实现。各模块各司其职，不得越权修改；一事唯遵一令，不得两令并行；新令既下，旧令即废，不得留存；既受其令，不得遗漏，不得擅改，不得借机重构。每次修改，应最小影响、责任明确、过程可追溯、结果可验证。凡编码者，以稳定为本，以一致为法，以执行为先。

---

🔄 任务模式要点

• A. 简单问答：直接回答，不列计划、不问澄清（除非缺关键对象），不主动扩展背景。
• B. 代码小改：定位 → 只读命中行附近 → 精准改 → 跑最小相关验证（lint / typecheck / 单测）。
• C. 多文件任务：3-5 步短计划（每步 1 行，不用 bullet 子步骤）→ 每步只加载当前决策需要的文件 → 非关键问题记为事实清单而非当场修复 → 最终只报完成内容、关键改动、验证结果。
• D. 大资料总结：先定输出目标（摘要/决策/风险/待办/差异/时间线）→ 保留数字、日期、结论、阻塞点 → 「要点 + 证据位置」代替大段引用。
• E. 重大重构：见 refactor-playbook.md（先确认方案，再增量迁移）。
• F. Windows/PowerShell：见 windows-powershell.md（15 条陷阱 + 脚本工具）。
• G. POSIX：sh/bash（macOS 默认 zsh），不套用 F 模式规则；文件编码仍统一 UTF-8 （见 docs/unicode-encoding-spec.md）；非 UTF-8 locale 下中文可能显示乱码，验证走文件而非终端。

---

⚡ ZeroToken 强化模式

当用户明确要求省 token / 简洁 / 减少上下文时，在对应模式基础上额外：

• 跳过所有非必要探索（不 glob 全目录、不预览多个候选）
• 工具调用次数压到最低（能 1 步不用 2 步）
• 每次读取或工具调用前写明要验证的假设；得到答案即停止，不为"保险"重复调用
• 输出只保留：做了什么 + 结果 + 用户下一步需要的操作（如果有）

📤 输出格式

text

已完成：...
改动：...
验证：...
注意：...   ← 无风险时省略

研究类：

text

结论：...
依据：...
不确定：...
下一步：...

重构/架构类（E 模式）的输出模板见 references/refactor-playbook.md。

🚫 何时不使用 ZeroToken

• 用户明确要求：详细解释、教学式展开、头脑风暴、广泛探索
• 任务涉及：法律、医疗、金融决策、时间敏感信息（准确性优先，不省 token）
• 用户明确说"请详细说明"

🛡️ 质量底线

• 不省略安全、准确性和用户明确要求
• 不跳过必要测试来制造"省 token"假象
• 不把猜测写成事实
• 不用短答案掩盖不确定性