{"id":"bce9a77d-19d3-46a5-bfa4-247eef1bea56","entityType":"agent","slug":"clawhub-phoenixlucky-zerotoken-skill","name":"ZeroToken","canonicalUrl":"https://www.xpersona.co/agent/clawhub-phoenixlucky-zerotoken-skill","canonicalPath":"/agent/clawhub-phoenixlucky-zerotoken-skill","generatedAt":"2026-10-09T21:52:46.333Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T15:15:09.724Z","emptyReason":null},"description":"Token-efficient, safe agent execution Skill: ZeroToken Owner: phoenixlucky Summary: Token-efficient, safe agent execution Tags: agent-discipline:1.6.0, latest:1.17.0, token-efficient:1.6.0, zerotoken:1.6.0 Version history: v1.17.0 | 2026-09-20T07:34:38.599Z | user 安全：移除未受信任桥脚本探测与执行（修复审计 T07）并补充第三方数据外发提示；audit_encoding 移除 .env 避免误报；收窄 SKILL.md 自动触发条件；fix_encoding 无 --backup 时告警 v1.16.0 | 2026-09-20T05:42:26.932Z | user 新增站内锚点与脚本引用审计；回归测试自动发现；README 瘦身 45%","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.4K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17705e3p3j221cp70a66wbscd844f38:zerotoken-skill","sourceUrl":"https://clawhub.ai/phoenixlucky/zerotoken-skill","homepage":"https://clawhub.ai/phoenixlucky/skills/zerotoken-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/phoenixlucky/zerotoken-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/phoenixlucky/skills/zerotoken-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Token-efficient, safe agent execution Skill: ZeroToken Owner: phoenixlucky Summary: Token-efficient, safe agent execution Tags: agent-discipline:1.6.0, latest:1"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:15:09.724Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:15:09.724Z","emptyReason":null},"stars":null,"forks":null,"downloads":2413,"packageName":null,"latestVersion":"1.17.0","tractionLabel":"2.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T15:15:09.687Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T15:15:09.724Z","lastCrawledAt":"2026-10-09T15:15:09.687Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T15:15:09.687Z","lastVerifiedAt":null,"highlights":[{"version":"1.17.0","createdAt":"2026-09-20T07:34:38.599Z","changelog":"安全：移除未受信任桥脚本探测与执行（修复审计 T07）并补充第三方数据外发提示；audit_encoding 移除 .env 避免误报；收窄 SKILL.md 自动触发条件；fix_encoding 无 --backup 时告警","fileCount":33,"zipByteSize":271512},{"version":"1.16.0","createdAt":"2026-09-20T05:42:26.932Z","changelog":"新增站内锚点与脚本引用审计；回归测试自动发现；README 瘦身 45%；banner 重压 72%；含未发布的 1.15.0 编码/BOM 与体积预算调整","fileCount":33,"zipByteSize":270458},{"version":"1.14.0","createdAt":"2026-09-15T08:05:15.617Z","changelog":"v1.14.0: 统一命令入口 zt.py、--json 输出、bump_version 写入修复、文档分层到 references/","fileCount":30,"zipByteSize":685248},{"version":"1.13.2","createdAt":"2026-08-28T02:08:11.363Z","changelog":"v1.13.2: README version badge fix","fileCount":21,"zipByteSize":665407},{"version":"1.13.1","createdAt":"2026-08-28T01:56:14.632Z","changelog":"v1.13.1: README 平台集成指南补发——方式一标注（推荐，AI助手安装）；方式二/三补充 GitHub 源安装命令，与 ClawHub 源并列（docs-only patch）","fileCount":21,"zipByteSize":665312},{"version":"1.13.0","createdAt":"2026-08-28T01:39:42.165Z","changelog":"v1.13.0: 新增 ClawHub 发布规范章节（C1-C5 陷阱 + 固定发布时序）：ClawHub 非 git 端点须用 clawhub CLI 发布（绝对路径+dry-run+后台运行）；PowerShell curl 别名用 curl.exe；安全扫描异步用 inspect 复查；发布前工作区必须干净","fileCount":21,"zipByteSize":665094},{"version":"1.12.0","createdAt":"2026-08-28T01:26:17.830Z","changelog":"v1.12.0: 新增 detect_env.py 环境识别（OS/Shell/控制台编码/中文支持/PowerShell 版本，持久化到 .zerotoken/environment.json，7 天有效期）；新增 G 模式 POSIX 工作流；核心原则 #8 先识别环境再选 Shell；F 模式改为 Windows 自动启用；init_env.ps1 新增 [0.5] 系统参数识别段并修复 psEdition 变量冲突；新增 test_detect_env.py 回归测试","fileCount":23,"zipByteSize":713105},{"version":"1.10.0","createdAt":"2026-08-10T06:18:21.458Z","changelog":"版本 1.10.0：文档排版与结构规范化（修复 SKILL.md 未闭合代码块、顶层章节统一 emoji 前缀、README 与 SKILL.md 去重为单一信息源）；搜索资料规范放宽（Chrome MCP 搜索引擎不限百度，不可用时允许其他搜索方式）；落地 Unicode 安全编码规范（新增 docs/unicode-encoding-spec.md 与 scripts/audit_encoding.py）；全部 Python 脚本 UTF-8 安全加固","fileCount":18,"zipByteSize":63416}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17705e3p3j221cp70a66wbscd844f38:zerotoken-skill","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T21:52:46.330Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-phoenixlucky-zerotoken-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T15:15:09.724Z","emptyReason":null},"readme":"Skill: ZeroToken\n\nOwner: phoenixlucky\n\nSummary: Token-efficient, safe agent execution\n\nTags: agent-discipline:1.6.0, latest:1.17.0, token-efficient:1.6.0, zerotoken:1.6.0\n\nVersion history:\n\nv1.17.0 | 2026-09-20T07:34:38.599Z | user\n\n安全：移除未受信任桥脚本探测与执行（修复审计 T07）并补充第三方数据外发提示；audit_encoding 移除 .env 避免误报；收窄 SKILL.md 自动触发条件；fix_encoding 无 --backup 时告警\n\nv1.16.0 | 2026-09-20T05:42:26.932Z | user\n\n新增站内锚点与脚本引用审计；回归测试自动发现；README 瘦身 45%；banner 重压 72%；含未发布的 1.15.0 编码/BOM 与体积预算调整\n\nv1.14.0 | 2026-09-15T08:05:15.617Z | user\n\nv1.14.0: 统一命令入口 zt.py、--json 输出、bump_version 写入修复、文档分层到 references/\n\nv1.13.2 | 2026-08-28T02:08:11.363Z | user\n\nv1.13.2: README version badge fix\n\nv1.13.1 | 2026-08-28T01:56:14.632Z | user\n\nv1.13.1: README 平台集成指南补发——方式一标注（推荐，AI助手安装）；方式二/三补充 GitHub 源安装命令，与 ClawHub 源并列（docs-only patch）\n\nv1.13.0 | 2026-08-28T01:39:42.165Z | user\n\nv1.13.0: 新增 ClawHub 发布规范章节（C1-C5 陷阱 + 固定发布时序）：ClawHub 非 git 端点须用 clawhub CLI 发布（绝对路径+dry-run+后台运行）；PowerShell curl 别名用 curl.exe；安全扫描异步用 inspect 复查；发布前工作区必须干净\n\nv1.12.0 | 2026-08-28T01:26:17.830Z | user\n\nv1.12.0: 新增 detect_env.py 环境识别（OS/Shell/控制台编码/中文支持/PowerShell 版本，持久化到 .zerotoken/environment.json，7 天有效期）；新增 G 模式 POSIX 工作流；核心原则 #8 先识别环境再选 Shell；F 模式改为 Windows 自动启用；init_env.ps1 新增 [0.5] 系统参数识别段并修复 psEdition 变量冲突；新增 test_detect_env.py 回归测试\n\nv1.10.0 | 2026-08-10T06:18:21.458Z | user\n\n版本 1.10.0：文档排版与结构规范化（修复 SKILL.md 未闭合代码块、顶层章节统一 emoji 前缀、README 与 SKILL.md 去重为单一信息源）；搜索资料规范放宽（Chrome MCP 搜索引擎不限百度，不可用时允许其他搜索方式）；落地 Unicode 安全编码规范（新增 docs/unicode-encoding-spec.md 与 scripts/audit_encoding.py）；全部 Python 脚本 UTF-8 安全加固\n\nv1.9.1 | 2026-08-07T07:49:59.765Z | auto\n\n**zerotoken-skill v1.9.1 — adds encoding audit/Unicode spec, doc improvements**\n\n- Added `scripts/audit_encoding.py` for code/text encoding auditing.\n- Added `docs/unicode-encoding-spec.md` with Unicode encoding specification details.\n- Improved documentation and discipline guidance in AGENTS.md, README.md, and SKILL.md.\n- Removed deprecated file: `skill-card.md`.\n- Updated and refined existing encoding, batch edit, and environment scripts.\n\nv1.9.0 | 2026-08-07T05:04:04.922Z | auto\n\nzerotoken-skill 1.9.0\n\n- Added the \"AI 编程总纲（尉缭子十原则）\" section to the documentation, outlining key principles for responsible code changes and project discipline.\n- Improved and clarified task mode documentation, especially structure and project management guidance.\n- Removed the redundant skill-card.md file.\n- General documentation updates and refinements in SKILL.md, README.md, and CHANGELOG.md.\n- Updated metadata and package information to reflect the new version and documentation improvements.\n\nv1.8.2 | 2026-07-24T02:59:03.473Z | user\n\n适配 browser-localmcp-skills，新增搜索规范和 Windows 兼容改进，修复 safe_io 编码问题\n\nv1.8.1 | 2026-07-22T06:29:41.234Z | user\n\n增强搜索规范：新增 Chrome MCP 能力范围说明、禁用行为三项硬约束，F 模式新增陷阱 #5\n\nv1.7.2 | 2026-07-21T07:12:51.519Z | auto\n\nVersion 1.7.2\n\n- Updated documentation in SKILL.md to reflect recent clarifications and improvements.\n- Incremented version in SKILL.md and package.json from 1.7.1 to 1.7.2.\n- General documentation maintenance: improvements to accurate description of features, security, and usage guidelines.\n- No changes to logic, features, or user-facing functionality.\n\nv1.7.1 | 2026-07-21T07:08:00.475Z | auto\n\n**zerotoken-skill 1.7.1** — Adds GBK-contamination detection/repair and improves cross-platform file safety.\n\n- Adds scripts/detect_gbk_contamination.py for detecting and fixing PowerShell GBK-polluted UTF-8 files.\n- Expands security disclosure: new gbk-contamination-detection capability.\n- Documents and enforces safe_append (Python-based) as the only valid way to append text to UTF-8 files on Windows/PowerShell to prevent encoding corruption.\n- Updates F-mode (Windows/PowerShell+Chinese) guide with an additional 8th common pitfall and countermeasures.\n- All \"plan\" steps must be single-line top-level items to ensure correct task progression.\n- Documentation and tool usage guidance improved for multilingual and cross-platform workflows.\n\nv1.7.0 | 2026-07-21T07:04:33.754Z | auto\n\nzerotoken-skill 1.7.0 — Adds GBK encoding contamination detection/repair and improves cross-platform file-safety.\n\n- New: GBK编码污染检测与修复脚本（scripts/detect_gbk_contamination.py），可检测/修复 PowerShell Add-Content 等带来的 UTF-8 文件尾部乱码。\n- 增强安全声明，明示支持安全追加（safe_append）、GBK污染检测等文件系统工具能力。\n- F（Windows/PowerShell中文环境）模式陷阱列表扩展为8条，新增Add-Content导致文件污染问题说明与替代方案。\n- 文档细化，明确中文交互需用户显式opt-in；常规场景默认英文提示策略。\n- safe_io.py增强，支持文件安全追加，补充文档与用例。\n- skill-card.md（遗留/重复）文件已移除，精简文档结构。\n\nv1.6.2 | 2026-07-10T05:04:55.598Z | auto\n\n**Changelog for zerotoken-skill v1.6.2**\n\n- Clarified security and permission disclosures in documentation (SKILL.md).\n- Explicitly documented that `reasonix.toml` declares general tool permissions and that `init_env.ps1` only updates local git config, not global.\n- No changes to functional logic or capabilities; documentation, metadata, and security information improved for cross-platform and integration clarity.\n- Minor updates to metadata version and inline doc explanations to match current permissions and environment behavior.\n\nv1.6.1 | 2026-07-10T03:40:37.257Z | auto\n\nzerotoken-skill v1.6.1\n\n- Added explicit capability and security disclosures to documentation, including file system operations and conditional platform dependencies.\n- Updated SKILL.md to clarify language/platform scope and to declare permissions and safety-related behaviors.\n- No behavioral logic changes; this is a documentation and metadata update to meet clarity and compliance standards.\n\nv1.6.0 | 2026-07-10T03:15:25.330Z | user\n\nAdded: scripts/ utilities (safe_io, batch_edit, fix_encoding, verify_output, init_env), .gitattributes for Windows/PowerShell+Chinese environment. Updated: SKILL.md F mode with scripts references.\n\nv1.4.0 | 2026-06-09T09:05:39.213Z | user\n\nAdded E. 重大重构/架构调整 task mode\n\nv1.3.0 | 2026-06-03T09:43:49.054Z | user\n\nDeduplicate README, trim keywords (24→7), relicense to GPL-3.0, fix CHANGELOG duplicate\n\nv1.2.0 | 2026-05-29T08:18:47.342Z | auto\n\nVersion 1.2.0 of zerotoken-skill\n\n- Major rewrite of SKILL.md: condensed skill description, added quick reference table, clarified core principles and modes, simplified prompt and output templates.\n- Improved user guidance for when to activate/deactivate ZeroToken mode.\n- More explicit rules for minimal tool usage and concise context handling.\n- LICENSE file added; skill-card.md removed.\n- Documentation (README.md, CHANGELOG.md) and metadata (package.json, agent YAML) updated for new version.\n\nv1.0.3 | 2026-04-27T07:45:09.100Z | user\n\nExpanded package keywords for prompt engineering, context optimization, token budgeting, and agent workflow discovery.\n\nv1.0.0 | 2026-04-27T07:11:56.868Z | user\n\nInitial release. Added the ZeroToken skill for token-efficient task execution, plus the minimal publishing files package.json, README.md, and CHANGELOG.md.\n\nArchive index:\n\nArchive v1.17.0: 33 files, 271512 bytes\n\nFiles: AGENTS.md (2718b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (165378b), CHANGELOG.md (25710b), docs/unicode-encoding-spec.md (8968b), LICENSE (35792b), package.json (918b), README.md (10654b), references/publishing-clawhub.md (3690b), references/refactor-playbook.md (2756b), references/search.md (3732b), references/tool-mapping.md (3102b), references/windows-powershell.md (13292b), scripts/audit_encoding.py (6206b), scripts/audit_skill.py (14209b), scripts/batch_edit.py (3690b), scripts/bump_version.py (4679b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9311b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_audit_encoding.py (1806b), scripts/test_audit_skill.py (3348b), scripts/test_bump_version.py (3512b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/test_zt.py (2162b), scripts/verify_output.py (5081b), scripts/zt.py (9791b), skill-card.md (2630b), SKILL.md (12264b), _meta.json (135b)\n\nFile v1.17.0:SKILL.md\n\n---\nname: zerotoken-skill\nversion: 1.17.0\ndescription: Token-efficient assistant discipline for concise, direct answers and minimal-context task execution. Use only when the user explicitly requests low-token / direct output (e.g. says「省 token」「直接给结果」) or invokes this skill by name; includes optional file-encoding and Windows PowerShell utilities (single entry: `python scripts/zt.py help`).\nmetadata:\n security:\n capabilities:\n - filesystem-read: \"read local files\"\n - filesystem-write: \"write/modify local files\"\n - batch-edit: \"apply multiple text replacements to a single file\"\n - encoding-conversion: \"batch file encoding detection and conversion\"\n - gbk-contamination-detection: \"detect and repair GBK-contaminated UTF-8 files\"\n - git-operations: \"git config and commit operations\"\n permissions-declared: true\n language: \"回答语言跟随用户交互语言（用中文问就中文答）；文档正文为 zh-CN\"\n platforms: \"auto-detects OS at session start (detect_env.py): Windows/PowerShell -> Mode F, Linux/macOS -> Mode G\"\n references: \"细节按需读取 references/*.md（Windows 陷阱 / 重构手册 / 搜索规范 / 发布手册 / 工具映射）\"\n---\n\n# ZeroToken Skill\n\n> **语言**：回答语言跟随用户交互语言——用中文问就用中文答，用英文问就用英文答\n> （语言可自选；本文件正文用 zh-CN 只是默认，不强制）。\n> 平台环境由 `python scripts/detect_env.py` 自动识别，不需要用户声明语言或平台。\n> *(Answer in the user's language; environment detection is automatic.)*\n\n用最少必要 token 和最精准提示词完成任务。省 token ≠ 偷工减料；核心是减少无效上下文、无效解释、无效工具调用、无效输出。\n\n> **🛡️ 能力与安全披露**（安装前请确认符合你的安全策略）\n> 除提示词纪律外，本 Skill 还声明这些文件系统能力：\n> 读取/修改本地文件（`read_file`/`edit_file`/`write_file`）；批量替换与编码转换\n> （`scripts/batch_edit.py`、`fix_encoding.py`）；安全读写与追加（`scripts/safe_io.py`，\n> 规避 `Add-Content` 的 GBK 污染）；GBK 污染检测修复（`scripts/detect_gbk_contamination.py`）；\n> Git 配置（`scripts/init_env.ps1` 只改**当前仓库 local 配置**，不动全局）；\n> 环境探测结果写 `.zerotoken/environment.json`（7 天有效期，已 gitignore）。\n\n---\n\n## 📐 快速决策表\n\n| 用户请求特征 | 模式 | 首轮输出 | 工具偏好 |\n|---|---|---|---|\n| 问定义/翻译/短建议 | **A. 简单问答** | 1-5 句直接回答 | 直接输出，不跑工具 |\n| 单文件修复/配置调整 | **B. 代码小改** | 改动 + 验证结果 | `grep` → `read_file`(局部) → `edit_file` |\n| 跨模块功能/常规重构/CI | **C. 多文件任务** | 3-5 步短计划 | `glob` → `grep` → 分批 `read_file` |\n| 长文/日志/PR/文档总结 | **D. 大资料总结** | 要点 + 证据位置 | `read_file`(head+tail) → `grep`(关键行) |\n| 反复出同类 bug / 加功能越来越难 / 架构与需求不匹配 | **E. 重大重构/架构调整** | 问题诊断 + 目标方案 + 迁移路线图 | `explore` → 分批 `read_file`（详见 [`references/refactor-playbook.md`](references/refactor-playbook.md)） |\n| 用户明确说\"省 token\" | **ZeroToken 强化** | 最短可执行输出 | 同上，但跳过所有非必要探索 |\n| 用户说\"详细解释/教学\" | **➡ 退出 ZeroToken** | 常规详尽模式 | 不限 |\n| 系统是 Windows/PowerShell（detect_env.py 自动识别） | **F. Windows/PowerShell 环境适配** | 系统参数已保存，按陷阱规则调整工作流 | 详见 [`references/windows-powershell.md`](references/windows-powershell.md) |\n| 系统是 Linux/macOS（detect_env.py 自动识别） | **G. POSIX 标准工作流** | 按 POSIX 规则工作，禁用 PowerShell 语法 | 常规 shell 工具链（sh/bash/zsh） |\n\n> 工具名以当前宿主实际提供的为准；名字不同时见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n\n---\n\n## 🧭 核心原则\n\n1. **先分类，再预算** — 按上表决定上下文深度，不默认全量读取。\n2. **压缩提示词** — 目标 + 已知输入 + 约束 + 验收格式；只在缺失项会改变结果时追问。\n3. **渐进读取** — 先定位（`grep`/`glob`），再局部读，读完即停。大文件（70KB+）用 `read_file` 的 `offset` + `limit` 分页，避免被截断。\n4. **先给结果** — 结论或完成状态先行；解释、推理按需补充。\n5. **不复述** — 不重复用户问题、不写礼貌铺垫、不解释常识。\n6. **plan 只写顶层步骤，不写子 bullet** — 每个 phase 写 1 行（共 2-5 个），细节放说明文字里。宿主把 bullet 注册成独立待办时的规避细节、签收证据规则见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n7. **设置停止条件** — 已定位目标、必要调用方/数据源和验证方式后停止搜索；同一文件未变化时不重复读取。\n8. **先识别环境，再选 Shell** — 任何涉及命令行执行的任务，第一步：\n `python scripts/detect_env.py` → `.zerotoken/environment.json`（7 天有效期）。\n 之后所有命令按已保存的系统参数选择：Windows 一律 PowerShell（禁用 bash），\n Linux/macOS 用 sh/bash/zsh；中文支持能力以 `console.cjk_capable` 为准。\n\n---\n\n## 📚 参考文档（按需读取）\n\n| 文档 | 何时读 |\n|---|---|\n| [`windows-powershell.md`](references/windows-powershell.md) | 命中 F 模式；编码/乱码/GBK/PowerShell/附件读取问题 |\n| [`refactor-playbook.md`](references/refactor-playbook.md) | 命中 E 模式：诊断 → 方案 → 增量迁移 |\n| [`search.md`](references/search.md) | 需要外部资料、浏览器搜索、社交平台内容 |\n| [`tool-mapping.md`](references/tool-mapping.md) | 工具名与本文不符；宿主有 plan/待办/签收机制 |\n| [`publishing-clawhub.md`](references/publishing-clawhub.md) | **仅维护者**：发布新版本到 ClawHub |\n\n> 🔧 **工具入口：** `python scripts/zt.py help`（`zt.py check` 一键跑完全部校验）\n\n### 🚨 Windows 三条致命项（必守）\n\n1. **别用 `Add-Content` / `Set-Content` 写中文** — PS 5.1 默认按 GBK 写出，emoji 会静默变 `?`；改用 `safe_io.safe_write()` / `safe_append()`。\n2. **`Get-Content` 的中文乱码多是显示层假乱码** — 文件没坏；改用 `read_file` 或 `-Encoding UTF8`，禁止据乱码盲目转码重写。\n3. **命令行不内联中文**（`python -c \"中文\"`、含 `+`/反引号的参数）— 写 `.py` 脚本再 `python \"script.py\"` 执行。\n\n---\n\n## 📝 精准提示词模板\n\n```text\n目标：<要解决什么>\n输入：<数据/代码/错误/位置>\n约束：<不能做什么/必须满足什么>\n输出：<格式/字段/长度/验收标准>\n预算：<直接回答 / 最小读取 / 需要验证>（可省略，默认最小读取）\n```\n\n请求含糊时先用此模板提炼；只有缺关键输入才追问，一次只问 1 个问题。\n\n---\n\n## ⚔️ AI 编程总纲（尉缭子十原则）\n\n> **将军受命，君必先谋于庙，行令于廷，君身以斧钺授将。曰：左、右、中军皆有分职；若逾分而上请者死；军无二令，二令者诛；留令者诛；失令者诛。**\n\n核心不是军事，而是 **权限边界、单一指令、责任明确、执行一致**。与 ZeroToken 纪律互补：省 token 是效率，尉缭子是秩序。\n\n| # | 原则 | 要求 | 违反示例 |\n|---|---|---|---|\n| 1 | **先谋后动（谋于庙）** | 编码前先理解需求、明确目标、列出约束与方案，确认后再实现 | 边思考边改大量代码 |\n| 2 | **统一方案（行令于廷）** | 全仓库统一架构/命名/目录/接口/风格 | 一个问题多个实现、新旧逻辑混用 |\n| 3 | **职责明确（分职）** | 每层各司其职（UI→Service→Repository→DB），不得越级 | UI 直连数据库 |\n| 4 | **不得越权（逾分请者）** | 只改自己职责范围；修 SQL 不顺手改页面/接口/重构 | 顺手重构整个系统 |\n| 5 | **唯一命令（军无二令）** | 任何时刻只有一个最终需求；新需求先确认：废弃/覆盖/追加原需求 | 同时执行互相冲突的需求 |\n| 6 | **禁止旧令（留令者）** | 需求更新后旧方案立即失效，删除/替换/迁移，不留兼容层 | \"为了兼容以前\"偷偷保留旧代码 |\n| 7 | **严格执行（失令者）** | 已确认要求全部落实：功能/性能/注释/测试/边界情况 | 遗漏边界情况 |\n| 8 | **最小改动** | 修改范围越小越好，不影响已有功能；每次提交只解决一个问题 | 无关优化/重构 |\n| 9 | **可追溯** | 每次修改说明：为什么改、改了哪些文件/函数、影响、如何验证 | 修改历史无法追踪 |\n| 10 | **验证先于结束** | 编译/运行/需求/边界/回归全部验证通过才宣布完成 | 编码完就宣布结束 |\n\n**与任务模式的对应**：E 模式内置 #1（先诊断方案）、#8（不提前优化）、#10（每步验证）；\nB/C 模式动手前一句话确认需求 = #5；输出格式的「改动 / 验证 / 注意」= #9 + #10。\n\n### System Prompt 总纲\n\n> 臣缭以为：AI 编程，当先谋后动，后行其令。未明需求，不得编码；未定方案，不得实现。各模块各司其职，不得越权修改；一事唯遵一令，不得两令并行；新令既下，旧令即废，不得留存；既受其令，不得遗漏，不得擅改，不得借机重构。每次修改，应最小影响、责任明确、过程可追溯、结果可验证。凡编码者，以稳定为本，以一致为法，以执行为先。\n\n---\n\n## 🔄 任务模式要点\n\n- **A. 简单问答**：直接回答，不列计划、不问澄清（除非缺关键对象），不主动扩展背景。\n- **B. 代码小改**：定位 → 只读命中行附近 → 精准改 → 跑最小相关验证（lint / typecheck / 单测）。\n- **C. 多文件任务**：3-5 步短计划（每步 1 行，不用 bullet 子步骤）→ 每步只加载当前决策需要的文件 →\n 非关键问题记为事实清单而非当场修复 → 最终只报完成内容、关键改动、验证结果。\n- **D. 大资料总结**：先定输出目标（摘要/决策/风险/待办/差异/时间线）→ 保留数字、日期、结论、阻塞点 →\n 「要点 + 证据位置」代替大段引用。\n- **E. 重大重构**：见 [`refactor-playbook.md`](references/refactor-playbook.md)（先确认方案，再增量迁移）。\n- **F. Windows/PowerShell**：见 [`windows-powershell.md`](references/windows-powershell.md)（15 条陷阱 + 脚本工具）。\n- **G. POSIX**：sh/bash（macOS 默认 zsh），不套用 F 模式规则；文件编码仍统一 UTF-8\n （见 `docs/unicode-encoding-spec.md`）；非 UTF-8 locale 下中文可能显示乱码，验证走文件而非终端。\n\n---\n\n## ⚡ ZeroToken 强化模式\n\n当用户明确要求省 token / 简洁 / 减少上下文时，在对应模式基础上额外：\n\n- 跳过所有非必要探索（不 glob 全目录、不预览多个候选）\n- 工具调用次数压到最低（能 1 步不用 2 步）\n- 每次读取或工具调用前写明要验证的假设；得到答案即停止，不为\"保险\"重复调用\n- 输出只保留：做了什么 + 结果 + 用户下一步需要的操作（如果有）\n\n## 📤 输出格式\n\n```text\n已完成：...\n改动：...\n验证：...\n注意：... ← 无风险时省略\n```\n\n研究类：\n\n```text\n结论：...\n依据：...\n不确定：...\n下一步：...\n```\n\n重构/架构类（E 模式）的输出模板见 [`references/refactor-playbook.md`](references/refactor-playbook.md)。\n\n## 🚫 何时不使用 ZeroToken\n\n- 用户明确要求：详细解释、教学式展开、头脑风暴、广泛探索\n- 任务涉及：法律、医疗、金融决策、时间敏感信息（准确性优先，不省 token）\n- 用户明确说\"请详细说明\"\n\n## 🛡️ 质量底线\n\n- 不省略安全、准确性和用户明确要求\n- 不跳过必要测试来制造\"省 token\"假象\n- 不把猜测写成事实\n- 不用短答案掩盖不确定性\n\nFile v1.17.0:README.md\n\n\n\n# ⚡ ZeroToken Skill\n\n**让 Agent 用最少的 token 做最准的事**\n\n> ⚔️ **先谋后动，军无二令 —— 省 token 是效率，尉缭子是秩序。**\n>\n> 💬 **用不完，根本用不完，妈妈再也不用担心我缺 token 了。**\n\n[]()\n[](LICENSE)\n[]()\n[](https://github.com/phoenixlucky/zerotoken-skill/actions/workflows/ci.yml)\n\n
\n\n> **ZeroToken Skill** 是一套为 AI Agent 设计的**提示词纪律规范**——在不降低回答准确性的前提下，压缩无效上下文、无效解释、无效工具调用和无效输出。\n>\n> 它解决的核心问题是：Agent 在任务中经常过度读取、过度思考、过度输出，导致一次对话消耗成千上万不必要的 token。本 Skill 通过一套可执行的**模式决策表 + 行为约束 + 工具链策略**，让 Agent 在每一个任务环节都有明确的\"省 token 行为准则\"。\n>\n> 🎯 **目标：** 用最精准的提示，做最少的往返，产最精炼的结果。\n>\n> ✅ **适用于：** Reasonix / Codex CLI / OpenCode / Hermes / Cline 等主流 Agent 工具。一次学习，全平台受益。\n\n\n\n
![\"ZeroToken](\"assets/zerotoken-banner.webp\")
\n\n
\n\n**⚡ 少即是多 — Less is More**\n\n
\n\nFile v1.17.0:_meta.json\n\n{\n \"ownerId\": \"kn7dpzpqn086by5pfg5sbf64zx80zr6m\",\n \"slug\": \"zerotoken-skill\",\n \"version\": \"1.17.0\",\n \"publishedAt\": 1789889678599\n}\n\nFile v1.17.0:references/publishing-clawhub.md\n\n# ClawHub 发布（skill 分发与同步）\n\n> 本文是**维护者手册**——使用者无需阅读。\n> 项目通过 ClawHub 分发：。\n> 以下规则来自实测发布过程，发布任何版本时必须遵守。\n\n## 关键事实\n\n- ❗ **ClawHub 不是 Git 端点** — 仓库远程 `clawhub` 只是发布页地址，\n `git fetch/push clawhub` 必然 404（`repository not found`）。**发布必须走 clawhub CLI**，\n 不能指望 git push。\n- 发布 CLI 由 pnpm 全局安装：`%LOCALAPPDATA%\\pnpm\\clawhub.CMD`\n （PowerShell `PATH` 未包含 pnpm 目录时直接调 `clawhub` 会「无法识别」，需用全路径）。\n- 登录状态用 `clawhub whoami` 验证（应输出 `phoenixlucky`）。\n- 新版本提交后 ClawHub 会跑**安全扫描**（异步、分钟级），**提交成功 ≠ 立即可见**。\n- 发布包内容以**发布时的工作区文件**为准：GitHub 提交 ≠ ClawHub 包同步。\n 打包范围由 `package.json` 的 `files` 字段声明（改目录结构时必须同步核对）。\n\n## 发布陷阱表（C 系，与 F 模式 #1-15 区分）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| C1 | **PowerShell `curl` 是别名** | `curl -s -o NUL https://...` 报「缺少参数 SessionVariable」 | PS 里 `curl` = `Invoke-WebRequest`（参数不兼容）；探测网络/API 一律用 **`curl.exe`** |\n| C2 | **`clawhub publish` 相对路径解析错误** | `publish .` 报 `Error: SKILL.md required` | CLI 默认 `--dir skills`（相对 workdir），相对路径找不到根目录 SKILL.md；✅ 传**绝对路径** |\n| C3 | **发布命令长时零输出** | 前台发布跑 2 分钟无输出被超时终止，ClawHub 无变化 | 上传 registry 需 5-6 分钟且**全程零输出**（易误判卡死）；✅ 用后台运行（`run_in_background`）+ 轮询等待 |\n| C4 | **安全扫描异步** | 发布提交成功（`Update submitted ... pending security scans before it becomes public`）但 registry/页面仍是旧版本号 | 平台规则：扫描通过才公开；✅ 用 `clawhub inspect phoenixlucky/zerotoken-skill --json` 或页面 `og:image` 复查，看到新版本号即已公开 |\n| C5 | **发布前工作区有未提交改动** | 工作区脏时发布，未提交改动**已随包上传 ClawHub** 但 GitHub 缺失，两端分叉 | ✅ 发布前先 `git status` 确认干净（或先提交）再发布；发布后复查 `git status` |\n| C6 | **带 source 参数触发上传 ticket 失效** | `publish ... --source-repo ... --source-commit ` 报 `Skill upload ticket is missing, used, or expired`（连续重试 + 等冷却无效） | 实测：**去掉 `--source-repo` / `--source-commit` 重试即成功**；source 元数据可发布后通过页面/GitHub 关联，不影响打包内容 |\n\n## 推荐发布时序（每次发布固定流程）\n\n```text\n0. git status 确认工作区干净；git log 记录待发布版本号\n1. 一键校验：python scripts/zt.py check\n （回归测试 + 编码审计 + 文档一致性 + 版本号三处联动；与 CI 同一条命令）\n2. git push origin main（GitHub 先行）\n3. clawhub publish <仓库绝对路径> --slug zerotoken-skill --owner phoenixlucky \\\n --version <新版本> --changelog \"<变更摘要>\" --no-input\n —— 先加 --dry-run 预览（应输出 Would publish @），\n 确认无误后移除 --dry-run 再次执行，并放后台运行（陷阱 C3）\n4. clawhub inspect phoenixlucky/zerotoken-skill 复查公开状态（异步，陷阱 C4）\n```\n\n> 版本号用 `python scripts/zt.py version ` 写入三处；`zt.py check` 与 CI 跑同一套校验。\n\nFile v1.17.0:references/refactor-playbook.md\n\n# E 模式参考：重大重构 / 架构调整\n\n> **触发信号**（满足任意一条即可进入此模式）：\n> - 同一模块反复修同一个类型的 bug，修了又犯\n> - 加一个小功能需要改 5+ 个文件，牵一发动全身\n> - 现有架构无法合理支持新需求，强行扩展会导致更深的 technical debt\n> - 测试覆盖率低、或测试需要大量 mock 才能跑，说明耦合度过高\n> - 代码逻辑纠缠不清，修改的「实际影响面」远超「预期影响面」\n>\n> 这是唯一**必须先确认方案再执行**的模式；其他模式识别即执行。\n\n## 流程\n\n1. **诊断根因，不治症状** — 先用跨文件探索工具（`explore`，或宿主提供的代码图工具）了解问题模块的全景（入口、调用链、数据流），定位系统性根源而非表面 bug。\n 产出：根因陈述（1-2 句话）。\n\n2. **评估影响面** — 摸清依赖关系：哪些模块依赖问题代码、哪些测试会受影响、是否有外部调用者。\n 产出：影响模块清单 + 风险等级。\n\n3. **设计方案 & 用户确认** — 输出 2-3 个候选方案的对比（每个含：核心思路、改动量、风险、迁移难度），\n 用 `ask` 让用户选择，**不要替用户做架构决策**。确认后再进入执行阶段。\n\n4. **制定增量迁移计划** — 将重构拆为可独立验证的小步，每步满足：\n - 可回滚（不破坏已有功能）\n - 可通过编译 + 已有测试\n - 新旧代码可共存过渡（strangler fig / feature flag / 适配层）\n 产出：`todo_write` 任务清单（顶层步骤，不含子 bullet）。\n\n5. **安全执行，每步验证** — 按计划逐步执行，每步后：\n - `lsp_diagnostics` 检查编译（宿主提供时）\n - 运行相关测试\n - 更新 `todo_write` 状态\n 发现计划外的依赖时暂停，补评估再继续。不得跳过验证走捷径。\n\n6. **清理收尾** — 删除废弃代码（不留「为了兼容以前」的旧实现，见总纲 #6）、移除过渡兼容层、\n 更新文档 / README / AGENTS.md。最后跑一次完整测试套件。\n\n## 输出模板（重构/架构类）\n\n```text\n问题：<根因 1-2 句>\n方案：<选定的方案简述>\n迁移计划：\n Step 1: <做什么> → 验证：<怎么验证>\n Step 2: ...\n风险：<已知风险和缓解措施>\n状态：进行中 | 已完成\n```\n\n## 关键原则\n\n- **先理解再动手**：E 模式允许较高的 token 消耗用于阅读和理解——诊断和设计方案阶段不做省 token 优化。\n- **不提前优化**：只重构当前确实有问题的部分，不顺手\"优化\"无关代码。\n- **留退出路径**：每一步都可以撤销或暂停，不做不可逆的一次性大改。\n\nFile v1.17.0:references/search.md\n\n# 搜索外部资料规范\n\n> 触发：任务需要外部资料（新闻、人物、公司、社交平台内容、实时信息等）。\n\n> ⚠️ **数据外发提示**：外部检索会把查询词发送给第三方（搜索引擎、目标网站、浏览器服务）。\n> 涉及敏感人名、未公开项目或专有信息时，先说明用途并征得用户同意，或改用本地/离线方式。\n\n## 优先级\n\n| 优先级 | 方式 | 条件 |\n|--------|------|------|\n| 🥇 宿主已注册的浏览器/检索工具 | 由宿主 MCP 注册表提供（如 `web_search` / `browser_navigate` / `web_fetch` 等当前会话实际可用的工具） | 在 `tools/list` 中存在 |\n| 🥈 用户显式授权的本地浏览器桥 | 用户给出**绝对路径**并确认后方可调用 | 用户显式授权且路径已核实 |\n\n> **为什么优先真实浏览器？** 纯 HTTP 抓取依赖搜索引擎结果页，曾被反爬返回完全无关内容；\n> 真实浏览器搜索（Playwright/Chrome）结果精准可控。\n\n## 只使用已注册的工具，不要探测文件系统\n\n检索入口**只从宿主已注册的工具中选择**（以当前会话实际可用的工具列表为准）。\n\n**禁止**在仓库或用户目录中通配扫描并执行 `mcp_call.py`、`mcp-bridge.js` 等文件：\n工作区中的同名文件可能来自其他技能或不受信任的来源，执行它等于把未授权的文件\n跨过信任边界提升为可执行工具，构成工具劫持风险。\n\n若当前没有可用的检索工具，按顺序处理：\n\n```text\n1. 回退到宿主自带的静态抓取工具（如 web_fetch）\n2. 都不可用 → 询问用户希望的检索方式\n```\n\n**仅当用户显式给出某个桥接脚本的绝对路径、并明确确认调用时**，才允许调用该脚本。\n调用前展示解析后的绝对路径；路径首次使用或与上次不同时，都要重新确认。\n不得在通配目录中自动发现，不得解引用用户未确认的路径。\n\n> Windows 上若用户确认使用某个 Python 包装脚本，调用方式见\n> [`windows-powershell.md`](windows-powershell.md) 陷阱 5（避免 PowerShell 引号嵌套与 GBK 破坏 JSON 参数）。\n\n## 真实浏览器能搜什么\n\n| 场景 | 示例 | 形态 |\n|------|------|------|\n| 🔍 通用搜索 | 搜索新闻、人物、事件 | `<已注册工具> search 关键词` |\n| 🐦 社交媒体动态 | 搜微博、知乎、小红书上的内容 | `<已注册工具> search 微博 关键词` |\n| 🏢 公司/产品信息 | 查询公司背景、产品评测 | `<已注册工具> search 公司名 评价` |\n| 📰 最新资讯 | 今日热点、行业动态 | `<已注册工具> search 今日 热点` |\n\n> **无需为每个平台找专用 MCP server** — 真实浏览器通杀反爬严格的网站；搜索引擎按检索效果自由选择。\n\n**若已注册的浏览器/检索工具不可用**：允许使用当前可用的其他抓取方式（如 `web_fetch`），\n不要因为首选方案不可用就放弃搜索。\n\n## 什么情况走抓取工具\n\n仅当以下条件**全部满足**时才回退：\n\n1. 已注册的浏览器/检索工具不可用\n2. 目标网站没有反爬（非社交平台、非登录墙）\n3. 仅需获取静态页面内容（非 SPA 页面）\n\n## ❌ 禁用行为\n\n- **禁止通配扫描并执行工作区/用户目录中的 `mcp_*.py`、`mcp-bridge.js` 等脚本** — 未注册来源不可信任\n- **禁止用抓取工具直抓社交媒体（微博/知乎/小红书等）** — 全部有登录墙/反爬，100% 失败\n- **禁止自己写 Playwright/Puppeteer 脚本绕过宿主已注册的工具链**\n- **禁止用抓取工具直连搜索引擎（Google/百度/Bing）** — 纯 HTTP 请求会被机器人检测拦截\n\nFile v1.17.0:references/tool-mapping.md\n\n# 工具名映射与宿主专属行为\n\n> 本 skill 描述的是**能力**，不是某个宿主的工具名。\n> 下表把本文档与 `SKILL.md` 中用到的能力映射到具体宿主工具；\n> 只调用当前宿主**实际提供**的等价工具，不要臆造名字。\n\n## 能力 → 工具名\n\n| 能力 | Reasonix | 其他宿主常见名 |\n|---|---|---|\n| 文本搜索（定位行） | `grep` | `search_content` / ripgrep / `grep` |\n| 文件枚举 | `glob` / `ls` | `directory_tree` / `find` / `list_dir` |\n| 局部读取 | `read_file`（`offset` + `limit`） | `read_file` / `open_file` |\n| 写入 / 编辑 | `write_file` / `edit_file` | `apply_patch` / `str_replace_editor` |\n| 同文件多处编辑 | `scripts/batch_edit.py`（宿主若提供 `multi_edit` 可优先用） | `multi_edit` |\n| 待办清单 | `todo_write` | `complete_step` / `update_plan` |\n| 跨文件探索 / 影响面 | `explore`（只读子代理） | `codegraph_context` / `codegraph_trace` / Task |\n| 结构化提问 | `ask` | `ask_user` |\n| 编译 / 类型检查 | `lsp_diagnostics` | `diagnostics` |\n| 网页抓取 | `web_fetch`（宿主提供时） | `fetch` / `browse` |\n\n> 代码图类工具（`codegraph_*`）若宿主提供，在 E 模式下优先于 `explore`——\n> 它给出的是调用链而非搜索命中。没有这类工具时，用 `explore` + `grep` 组合替代。\n\n## 宿主 verification 循环\n\n部分宿主（如带 AutoResearch 签收机制的宿主）会出现：验证证据已提供多次\n（git diff、文件检查、关键词检查），系统仍不接受，`stale_count` 持续累积。\n\n✅ 使用宿主提供的签收工具（如 `complete_step`，`kind: \"verification\"`）推进任务，\n而不是仅靠 `` 之类的文本块。\n✅ 签收证据的 `command` 字段必须与会话历史中的命令文本**完全一致**，否则被视为无效。\n✅ 宿主不提供签收工具时忽略本节——它是宿主行为，不是 Windows / 编码问题。\n\n## plan / todo 注册行为\n\n某些宿主的 plan 模式会把**每层 bullet 列表项**注册为独立待办项，且必须严格线性签收。\n规避方式：\n\n✅ 每个 phase 只写 1 行顶层步骤（共 2-5 个），细节写在说明文字中而非子 bullet。\n\n```text\n✅ 正确：\n1. safe_io.py 新增 safe_append 函数 — 用 open('a', encoding='utf-8') 替代 Add-Content\n\n❌ 错误（会生成 10+ 待办项）：\n1. safe_io.py 新增 safe_append\n - 实现函数\n - 更新文档字符串\n - 导出 __all__\n```\n\n若已陷入子步骤阻塞：优先用宿主的步骤调整机制（如 `complete_step({ step_index: N })`\n跳过中间项）直接签收当前卡住的项。\n\n**签收证据类型规则（宿主提供签收工具时）**\n\n- 工具写入的文件（`write_file` / `edit_file`）→ `files` 证据\n- 脚本写入的文件（如 Python 执行产物）→ `manual` 证据\n- `verification` 证据的 `command` 必须与会话历史中的命令文本完全一致\n- 每次工具调用只签一个步骤，按顺序推进（部分宿主限制：每轮只允许一个成功签收）\n\nFile v1.17.0:references/windows-powershell.md\n\n# F 模式参考：Windows / PowerShell 环境适配\n\n> **触发**：`python scripts/detect_env.py` 报告 `os.name == \"windows\"` 且推荐 shell 为 PowerShell。\n> 自动启用，**无需用户请求**，也不要求任务涉及中文。\n> 系统参数（OS 版本、控制台代码页、中文支持、PowerShell 发行版、Git quotepath）在探测时\n> 存入 `.zerotoken/environment.json`（7 天有效期），后续所有命令选择以保存的参数为准。\n>\n> **不适用**：macOS / Linux → 见 `SKILL.md` 的 G 模式，不要套用本文的规避规则。\n\n## 先决定：用编辑工具还是 Python 脚本\n\n| 情形 | 做法 |\n|---|---|\n| 纯 ASCII 内容、单处改动、文件本身是 UTF-8 | `edit_file` 直接改（B 模式默认路径） |\n| 内容含中文 / emoji / 特殊符号（`+`、反引号、`\\r\\n`） | `write_file` 写 `.py` 脚本，再 `python \"script.py\"` |\n| 同一文件需要多处改动（≥2 处） | 一个 Python 脚本一次完成，或用 `scripts/batch_edit.py` |\n| 批量编码转换 / GBK 污染修复 | `scripts/fix_encoding.py` / `scripts/detect_gbk_contamination.py` |\n| 命令参数本身含中文 | 写 `.py` 脚本执行，**不要**在命令行内联中文 |\n\n判定理由：PowerShell 命令行是编码 + 转义的双重雷区（见陷阱 1 / 8 / 11），\n而 Python 脚本的「写入脚本文件」和「执行脚本」两条路径都受 UTF-8 控制。\n\n## 已知陷阱与解决方案（15 条）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| 1 | **PowerShell 与中文文本冲突** | `bash` 工具传中文给 PowerShell，`+` 被解析为字符串拼接运算符；反引号 `` ` `` 被识别为转义字符；含中文的 PowerShell 字符串报 `Missing ')'` 语法错误 | ❌ 不要直接在 `bash` 命令中嵌入含 `+` 的中文
✅ 改为 `write_file` 写 `.py` 脚本文件，再用 `python \"script.py\"` 执行 |\n| 2 | **文件编码不一致** | 部分文件（如旧中文 Markdown）实际是 UTF-16 编码；Python 默认 UTF-8 读取抛 `UnicodeDecodeError`；旧文件中已有因编码损坏产生的替换字符（U+FFFD），导致字符串精确匹配失败 | ✅ 统一采用 UTF-8 编码读写
✅ 安全读取方案见下文的「安全文件读写模板」 |\n| 3 | **edit_file 同文件连续编辑阻塞**（宿主行为，与系统无关） | 同一文件的多处修改，第一次 `edit_file` 后第二次被拒，错误：`fresh read required — was already modified earlier this turn` | ✅ 对同一文件的多处修改，一次性用 Python 脚本完成
✅ 或用宿主提供的多编辑工具一次传入多个替换（≤5 个以内）
✅ 维护一个更新脚本，执行后统一验证 |\n| 4 | **Git 中文文件名转义显示** | `git diff --stat` 显示 `\\xxx\\xxx` 编码序列，无法直接阅读中文文件名 | ✅ 先执行 `git config core.quotepath false` |\n| 5 | **PowerShell → Node.js 中文 JSON 参数断裂** | 调用 `node mcp-bridge.js call tools/call '{\"name\":\"x\",\"arguments\":{\"url\":\"中文\"}}'` 时，中文导致 JSON 解析失败 | ✅ **不要直接调 `node mcp-bridge.js`**
✅ 改用 Python 包装脚本（本地 MCP 桥自带 `mcp_call.py`），其内部已用 `json.dumps()` 正确序列化 |\n| 6 | **宿主 verification 死循环**（宿主行为，与系统无关） | 验证证据已提供多次（git diff、文件检查、关键词检查），但系统始终不接受；`stale_count` 持续累积 | ✅ 见 [`tool-mapping.md`](tool-mapping.md) 的「宿主 verification 循环」 |\n| 7 | **Python 控制台输出中文失败** | Python 的 `print()` 在 PowerShell 控制台下因 GBK 编码报错：`UnicodeEncodeError: 'gbk' codec can't encode character` | ✅ 不直接 `print()`，写入 `.txt` 文件后用 `read_file` 查看
✅ 使用 `with open(out_path, 'w', encoding='utf-8') as f: f.write(result)` |\n| 8 | **PowerShell 中 `\\r\\n` 转义** | PowerShell 脚本中 `` `r`n `` 的反引号被解释为换行转义符，导致语法错误 | ✅ 不在 PowerShell 中拼接含换行的多语言文本
✅ 改用 Python 的 `\\n` 处理换行 |\n| 9 | **PowerShell Add-Content 使用 GBK 编码污染 UTF-8 文件** | 用 `Add-Content` 向 UTF-8 文件追加中文后，新内容变为乱码（GBK 字节被误读为 UTF-8，出现 U+FFFD 替换字符），文件末尾出现 `0x81` 等无效 UTF-8 字节
根因：PowerShell 的 `Add-Content` 默认使用系统区域编码（Windows 中文版为 GBK）写入 | ❌ **禁止直接使用 PowerShell Add-Content 追加含中文的内容**
✅ 使用 Python 安全追加：`open('file.md', 'a', encoding='utf-8').write('内容')`
✅ 或用 `safe_io.py` 的 `safe_append()` 函数
✅ 已污染的文件用 `detect_gbk_contamination.py` 检测修复 |\n| 10 | **PowerShell `&&` 链式操作不兼容** | PowerShell 不支持 bash 风格的 `&&` 运算符，`cmd1 && cmd2` 报语法错误 | ✅ 用 `;` 无条件链式
✅ 用 `if ($?) { ... }` 做条件链式 |\n| 11 | **内联 `python -c` 中文 SyntaxError** | `python -c \"含中文的代码\"` 在 PowerShell 下因编码问题导致 SyntaxError | ❌ 不要用 `python -c` 传入含中文的代码
✅ 改为 `write_file` 写 `.py` 脚本执行 |\n| 12 | **终端显示层中文乱码（文件内容正确）** | PowerShell 终端显示中文为乱码/问号，但文件内容实际正确（GBK 终端显示 UTF-8 编码文件） | ✅ 用文件大小/行数验证
✅ 用 `chcp 65001` 切换终端到 UTF-8 |\n| 13 | **PowerShell 读取附件时中文乱码显示** | 用 `Get-Content` / `type` 读取附件（用户上传的 .md/.txt/.csv 等）时中文显示为乱码（如 `鐗堟湰鍙?1.9.1`），但用 `read_file` 或编辑器打开内容正常
根因：Windows PowerShell 5.1 的 `Get-Content` 默认按 ANSI 代码页（中文系统为 GBK/936）解码无 BOM 的 UTF-8 文件，属**显示层**问题，文件本身未损坏
⚠️ 若把\"显示乱码\"误判为\"文件被污染\"并盲目转码重写，反而会造成真正的污染 | ✅ **优先用 `read_file` 工具读取附件**（按 UTF-8 解码，显示正确）
✅ 必须在 PowerShell 中读时显式指定编码：`Get-Content -Encoding UTF8 附件.md`（PS 7+ 默认 UTF-8；5.1 必须加 `-Encoding UTF8`）
✅ 附件本身是 GBK/UTF-16 等非 UTF-8 编码时，用 `safe_io.read_text()` 自动检测（UTF-8 BOM / UTF-16 BOM / GB18030）
✅ 先确认附件真实编码再处理；显示乱码≠文件损坏，禁止据此盲目转码 |\n| 14 | **PowerShell 写入命令默认编码不统一（写方向污染）** | PS 5.1 下 `Set-Content` / `Add-Content` 默认按 GBK 写出：纯汉字变成 GBK 字节（追加进 UTF-8 文件即污染），emoji 等字符**静默写成 `?` 丢字**；`Out-File` / `>` 重定向默认 UTF-16 LE（带 BOM）；`-Encoding UTF8` 写出的又是 UTF-8 **带 BOM**（部分工具解析异常）
已实测：同一 emoji 字符串经 `Set-Content` 默认写出为字节 `3F`（问号） | ✅ PowerShell 中写 UTF-8 文本统一用 .NET API：`[IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`（无 BOM；Append 用 `WriteAllText(..., $text, $enc)` 前先读原内容，或直接用 Python）
✅ 跨脚本/含中文的写入一律走 Python：`safe_io.safe_write()` / `safe_append()`（UTF-8 无 BOM + LF）
✅ 万不得已必须用 `Set-Content -Encoding UTF8` 时，知晓会带 BOM；禁止用其默认编码写任何非 ASCII 内容 |\n| 15 | **`Add-Content -Encoding UTF8` 追加不补换行导致粘连 + 带 BOM** | 即使显式指定 `-Encoding UTF8`，`Add-Content` 追加到不以换行结尾的文件时**不自动补换行**，两段内容直接粘连成一行（实测：`base` + 追加 → `base## 标题 ...`）；且写出的内容带 UTF-8 BOM | ✅ 追加操作改用 `safe_io.safe_append()`：自动补换行、UTF-8 无 BOM
✅ 纯 PowerShell 方案需自行判断末尾换行再拼接，复杂且易错，不建议
✅ 追加后发现首段粘连，检查是否由本陷阱导致，不要误判为内容错误 |\n\n## 脚本工具（`scripts/` 目录）\n\n**统一入口（推荐）：** `python scripts/zt.py <命令>` —— `zt.py help` 列出全部命令，\n`zt.py check` 一键跑完全部校验（回归测试 / 编码审计 / 文档一致性 / 版本联动）；\n参数原样透传，命令示例见 `zt.py help`。下表脚本均可独立调用（zt.py 只是转发）。\n\n仓库自带一系列 Python 脚本，开箱即用，覆盖 F 模式的常见操作：\n\n| 脚本 | 解决问题 | 用法示例 |\n|------|----------|----------|\n| `detect_env.py` | 环境识别：探测 OS / Shell / 控制台编码 / 中文支持 / PowerShell 版本并保存系统参数 | `python scripts/detect_env.py --force`（结果存 `.zerotoken/environment.json`，7 天有效期） |\n| `safe_io.py` | #2 编码不一致（UTF-8 BOM / UTF-16/32 BOM / GB18030） / #7 无法 print 中文 / #9 安全追加替代 Add-Content（自动补换行） / #13 附件乱码读取（自动检测编码） / #14 写方向编码统一（safe_write 无 BOM + LF） | `from safe_io import read_text, safe_write, safe_append, write_result`（编码无法确定时显式抛 `UnknownEncodingError`，不静默替换） |\n| `detect_gbk_contamination.py` | #9 检测修复 GBK 编码污染 | `python scripts/detect_gbk_contamination.py scan .` / `python scripts/detect_gbk_contamination.py fix . --backup` |\n| `batch_edit.py` | #3 edit_file 连续编辑阻塞 | `python scripts/batch_edit.py file.json replacements.json` |\n| `fix_encoding.py` | #2 批量编码转换 | `python scripts/fix_encoding.py scan .` / `python scripts/fix_encoding.py convert . --backup` |\n| `verify_output.py` | #7 控制台输出 / 验证结果落文件 | `python scripts/verify_output.py \"检查项\" out.txt --pass \"✓ 通过\"` |\n| `init_env.ps1` | #4 Git 配置 / 环境初始化 | 在新会话中 `. ./scripts/init_env.ps1` |\n\n## 推荐工作流\n\n当 `detect_env.py` 识别到 Windows 系统时，按以下步骤替代默认工作流：\n\n```text\n0. （首次）python scripts/detect_env.py 探测系统参数并保存\n （.zerotoken/environment.json，7 天有效；之后每次会话自动复用）\n1. 判断改动类型（见上文「先决定：用编辑工具还是 Python 脚本」）\n2. 需要脚本时：write_file 写 Python 更新脚本（.py）\n3. python \"script.py\" 执行（避免 PowerShell + edit_file 的所有问题）\n4. git diff --stat 验证文件变更\n5. 用 verify_output.py 输出验证结果到 .txt 文件\n6. read_file 读取验证结果\n7. 签收/收尾（宿主若提供 complete_step 等签收工具，见 references/tool-mapping.md）\n```\n\n## 安全文件读写模板\n\n优先直接调用 `safe_io`（`read_text` / `safe_write` / `safe_append`）；\n需要内联时使用等价写法：\n\n```python\n# 安全读取（UTF-8 / UTF-8 BOM / UTF-16 / GB18030 自动检测）\nwith open(path, 'rb') as f:\n raw = f.read()\n\nfrom safe_io import decode_bytes # 无法确定编码时显式抛错\ncontent = decode_bytes(raw, path)\n\n# 安全写入（统一 UTF-8，行尾 LF；newline='\\n' 防止 Windows 文本模式写成 CRLF）\nwith open(path, 'w', encoding='utf-8', newline='\\n') as f:\n f.write(content)\n\n# 安全追加（替代 Add-Content，避免 GBK 污染；newline='\\n' 同上）\nwith open(path, 'a', encoding='utf-8', newline='\\n') as f:\n f.write(content)\n if not content.endswith('\\n'):\n f.write('\\n')\n```\n\n## 不做什么\n\n❌ 不在 `bash` 命令中嵌入含特殊符号（`+`、`` ` ``）的中文字符串\n❌ 不连续对同一文件进行多次 `edit_file` 调用\n❌ 不直接在 PowerShell 中用 `print()` 输出中文\n❌ 不忽略 `git config core.quotepath` 设置\n❌ **不使用 PowerShell 的 `Add-Content` 追加含中文的内容** — 改用 Python `open(path, 'a', encoding='utf-8')` 或 `safe_io.safe_append()`\n❌ **不在 PowerShell 中直接调用 `node mcp-bridge.js` 传递中文 JSON 参数** — 改用 Python 包装脚本\n❌ **不用 `web_fetch` 直抓社交媒体（微博/知乎/小红书等）** — 100% 被登录墙或反爬拦截\n❌ **不自己写 Playwright/Puppeteer 脚本**（已有现成 MCP 桥，见 [`search.md`](search.md)）\n❌ **不使用 `python -c` 内联含中文的代码** — 改用 `write_file` + `python \"script.py\"` 两步法\n❌ **不使用 `&&` 链式命令** — PowerShell 不支持，改用 `;` 或 `if ($?) { ... }`\n❌ **不依赖终端输出验证中文内容** — 用文件内容验证替代\n❌ **不用 `Get-Content` 直接查看含中文的附件** — 5.1 默认按 GBK 解码会显示乱码，改用 `read_file` 工具或 `Get-Content -Encoding UTF8`；显示乱码≠文件损坏，禁止据此盲目转码\n❌ **不在 PS 5.1 中用 `Set-Content` / `Add-Content` / `Out-File` 的默认编码写任何非 ASCII 内容** — 默认 GBK 会污染 UTF-8 文件、emoji 静默变 `?`；写方向统一走 Python `safe_io.safe_write()` / `safe_append()`，或 .NET `[IO.File]::WriteAllText($path, $text, [Text.UTF8Encoding]::new($false))`\n❌ **不依赖 `Add-Content -Encoding UTF8` 做追加** — 仍会带 BOM 且目标不以换行结尾时不补换行导致内容粘连；统一用 `safe_io.safe_append()`\n\nFile v1.17.0:AGENTS.md\n\n# Project memory\n\n## 项目结构\n\n- `SKILL.md` — **常驻核心**（快速决策表 / 核心原则 / 输出格式 / 质量底线）。\n 体积预算 ≤14KB，超出即说明细节该外移到 `references/`。\n- `references/` — **按需读取**的细节：`windows-powershell.md`（F 模式 15 条陷阱）、\n `refactor-playbook.md`（E 模式）、`search.md`、`tool-mapping.md`、`publishing-clawhub.md`。\n- `scripts/` — 编码与一致性工具；`safe_io.py` 是其余脚本的公共依赖（`ensure_utf8_stdio` / `safe_print`）。\n- `docs/unicode-encoding-spec.md` — 编码规范的本仓库执行细则。\n- 分发：GitHub + ClawHub 双端；打包范围由 `package.json` 的 `files` 字段声明。\n\n## 校验命令（改完必跑，与 `.github/workflows/ci.yml` 一致）\n\n```powershell\npython scripts/zt.py check # 一键：回归测试 + 编码审计 + 文档一致性 + 版本联动\n```\n\n排查时单步跑（入口一览见 `python scripts/zt.py help`）：\n\n```powershell\npython scripts/zt.py env # 识别系统参数（写 .zerotoken/environment.json）\npython scripts/zt.py audit # 文档一致性：体积/链接/计数/脚本引用/异体字\npython scripts/zt.py encoding # 编码合规：UTF-8/替换字符/混合换行\npython scripts/zt.py version # 版本号三处联动（带版本号=写入）\n```\n\n> `check / audit / encoding / version` 支持 `--json [--out 文件]`（供 AI / CI 解析）；\n> `env / gbk / convert / edit / verify` 目前为文本输出。`scripts/` 下的原脚本仍可独立调用。\n\n## 发布（仅维护者）\n\n- 版本号一律用 `python scripts/zt.py version ` 写入三处，不要手改单点。\n- 发布时序、C1-C6 陷阱与 ClawHub CLI 用法见 `references/publishing-clawhub.md`；\n **ClawHub 不是 Git 端点**，`git push` 发不出去。\n\n## Notes\n\n- 方式二：从远程 Skill 仓库引用（推荐，始终获取最新版本） 安装这个技能 https://clawhub.ai/phoenixlucky/zerotoken-skill\n\n## 编码规范（必须遵守）\n\n- 生成/修改任何代码、配置、文档前，先读 `docs/unicode-encoding-spec.md`（Unicode 安全编码规范 15 条 + 项目执行细则）。\n- 硬性要求：文本文件统一 UTF-8（`.ps1` 例外必须 UTF-8 with BOM）；`open()` 一律显式 `encoding='utf-8'`；禁止 `errors='replace'` 静默损坏数据；Python 控制台输出优先 `sys.stdout.reconfigure(encoding='utf-8')`（本仓库统一走 `safe_io.safe_print`）；HTTP 头显式 `charset=utf-8`；JSON 用 `ensure_ascii=False`。\n- 完成后运行 `python scripts/audit_encoding.py --root . --out audit_result.txt` 检查（无 non-utf8、无替换字符、无混合换行）。\n\nFile v1.17.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## [1.17.0] - 2026-09-20\n\n### Security\n- `references/search.md` 移除对工作区/用户目录桥接脚本（`mcp_call.py`、`mcp-bridge.js`）\n 的通配探测与执行：检索入口只允许使用宿主已注册的工具；本地桥仅在用户显式给出绝对路径\n 并确认后才可调用。修复 ClawHub 安全审计 T07（Tool Hijacking and Spoofing ·\n Untrusted Local Browser Bridge Discovery and Execution），并补充第三方数据外发提示\n （原「Missing User Warnings」项）。\n- `scripts/audit_encoding.py` 从文本扩展名清单移除 `.env`，避免凭据访问类静态扫描误报。\n\n### Changed\n- `SKILL.md` 描述收窄自动触发条件：仅在用户明确要求省 token / 直接输出或点名调用本技能\n 时启用，移除易误触发的宽泛短语；并注明文档语言仅为默认、语言可自选。\n- `scripts/fix_encoding.py`：convert 未加 `--backup` 时显式告警（原地覆盖不可回滚），\n 消除文档与行为的歧义。\n\n## [1.16.0] - 2026-09-20\n\n### Added\n- `scripts/audit_skill.py` 新增第 10/11 项检查：站内 Markdown 锚点有效性\n （近似 github-slugger 规则还原锚点，兼容 emoji 标题）、每个非测试脚本\n 必须在文档中被引用（`scripts/test_*.py` 豁免，防新增脚本漏改清单）。\n- `scripts/test_zt.py` 回归测试（测试自动发现、路由退出码、help 输出）。\n- `package.json` 补 `repository` / `homepage` / `bugs` 元数据。\n\n### Fixed\n- README 指向 `SKILL.md` 的 4 个锚点失效：片段带了 emoji，而 GitHub 生成锚点时会\n 剥离 emoji（`#⚔️-ai-…` 实际应为 `#-ai-…`）；现由 audit_skill 锚点检查长期兜住。\n\n### Changed\n- README 深度瘦身（19304 B -> 10632 B，-45%）：新增目录；合并重复的安装方式；\n 把「场景详解 A-G」「尉缭子十原则全文」「搜索 / 编码 / 提示词 / 强化模式」等\n `SKILL.md` / `references/` 的副本改为摘要 + 入口（消除双份事实源）；\n 平台小节由 6 张卡片改为一张表；新增 CI 状态徽章；\n 修正「五种主流 Agent 工具」与 6 个小节的口径。\n- `assets/zerotoken-banner.webp` 重压为 720x1080 / q72：582 KB -> 165 KB（-72%）。\n\n## [1.15.0] - 2026-09-20\n\n### Added\n- `scripts/audit_skill.py` 新增第 9 项检查：CHANGELOG.md 顶部版本必须等于\n `package.json` 版本（版本号隐性第 4 处锚点，此前无机器校验）。\n- 回归测试 `scripts/test_audit_skill.py` / `scripts/test_audit_encoding.py`\n （合规 fixture 通过 + 注入缺陷命中），回归测试 3 -> 5 个。\n- `.editorconfig`：charset / eol / final-newline 的编辑器侧约束，与 `.gitattributes`\n 及编码规范一致；`.ps1` 标注 `utf-8-bom`。\n- `package.json` 增 `scripts.check`（等价 `python scripts/zt.py check`）。\n\n### Fixed\n- `scripts/audit_encoding.py` 纳入 BOM 规则校验：`.ps1` 必须 UTF-8 with BOM，\n 其余文本必须无 BOM（此前只统计不判违规）。\n- `scripts/audit_encoding.py` 改走 `safe_io`（`ensure_utf8_stdio` / `safe_print` /\n `safe_write`），消除「工具不守自身编码规范」的漂移。\n\n### Changed\n- `SKILL.md` 常驻体积预算 12KB -> 14KB（`audit_skill.py` 的 `SKILL_SIZE_BUDGET`），\n 并同步 `AGENTS.md` / `README.md` 口径；实占 12194 B，此前仅余 94 B。\n- `AGENTS.md` 修正「所有命令支持 `--json`」的表述：实际仅\n `check / audit / encoding / version` 支持，其余命令为文本输出。\n- `scripts/zt.py` 的 `check` 步骤改为自动发现 `scripts/test_*.py`，新增测试无需手改入口。\n\n## [1.14.0] - 2026-09-15\n\n### Added\n- `scripts/bump_version.py` — 版本号三处联动的校验与写入（`package.json` /\n SKILL.md frontmatter / README badge）。`--check` 供 CI 与发布前使用，\n 终结 v1.13.2 记录的「三处联动只能人工核对」漏改问题。\n- `scripts/audit_skill.py` — 文档一致性审计（8 项）：版本三处一致、SKILL.md 体积预算、\n Markdown 相对链接存在性、核心原则条数（SKILL.md vs README）、`scripts/*.py` 引用存在性、\n F 模式陷阱条数与文案声明一致、核心文档不得出现宿主专属工具名、\n 非规范 CJK 字符（康熙部首 / 兼容表意文字）。\n- `.github/workflows/ci.yml` — 最小 CI：两个回归测试 + 编码审计 + 文档一致性 + 版本联动。\n- `AGENTS.md` 补项目结构、校验命令、发布指针（原先只有编码规范与一条安装笔记）。\n\n### Fixed\n- SKILL.md 中的异体字：用 Kangxi 部首 U+2F0C 冒充「文」，视觉相同但码位不同，\n 搜索与精确匹配会静默失败。同类问题现由 `audit_skill.py` 长期兜住。\n- README 核心原则表长期只有 7 条：v1.12.0 新增的 #8「先识别环境，再选 Shell」未同步，\n 现由 `audit_skill.py` 强制两边条数一致。\n- **`bump_version.py` 写入路径崩溃**：`apply_version()` 依赖正则的第 3 组拼接文本，\n 而 SKILL.md 的锚点只有 2 组 → `python scripts/bump_version.py <版本号>` 抛\n `IndexError: no such group`，且此时 `package.json` 已被改写、另外两处未改（半写入状态）。\n 改为基于第 2 组的 `match.span()` 替换，对组数变化免疫；补 `test_bump_version.py` 兜住。\n （该路径自引入起只被 `--check` 覆盖过，写入分支从未被测 —— 教训：CLI 的写入分支必须有测试。）\n- `audit_encoding.py` / `bump_version.py` 统一返回退出码：发现问题返回 1\n （此前 `audit_encoding.py` 恒返回 0，CI 会把编码违规当成功放行）。\n\n### Changed\n- 文档统一以 zt.py 为主入口：`README.md`（F 模式段 + 文档地图）、\n `references/windows-powershell.md`（脚本工具段）、`AGENTS.md`（校验命令）、\n `references/publishing-clawhub.md`（发布时序 7 步 → 4 步，校验收敛为一条 `zt.py check`）、\n `.github/workflows/ci.yml`（5 个 step → 1 个）。\n- `bump_version.py` 的 `check()` 重构为 `gather()`（返回结构化结果，CLI 与 JSON 共用）。\n- `audit_encoding.py` 的 `--out` 默认值改为 `None`（默认行为仍是写 `audit_result.txt`；\n JSON 模式不落盘，除非显式 `--out`），避免 CI / `zt.py check` 污染工作区。\n- `SKILL.md` description 补中文触发词（「省 token / 简洁点 / 直接给结果 / 少废话 / 别解释」），\n 提高宿主自动加载命中率；新增一行工具入口指引（体积仍在 12KB 预算内）。\n\n### Tests\n- 新增负向探针验证：对仓库副本注入 8 类缺陷（版本漂移、坏链接、缺脚本引用、\n 原则条数不一致、陷阱条数漂移、宿主专属工具名、异体字），`audit_skill.py` 全部命中。\n\n## [1.13.2] - 2026-08-28\n\n### Fixed\n- **README 顶部版本徽章漏更新**：停在 `version-1.11.0`（v1.12.0 起 bump 只改\n `package.json` + `SKILL.md` frontmatter，README badge 未同步）。\n 已更新为 `version-1.13.2`。\n- 教训固化：**版本号 bump 是三处联动**（`package.json` / `SKILL.md` frontmatter /\n `README.md` 顶部 shield badge），发布节奏中应统一核对。\n\n## [1.13.1] - 2026-08-28\n\n### Changed\n- **README.md 平台集成指南更新**（补发到 ClawHub 发布包）：\n - 方式一标注「（推荐，AI助手安装）」\n - 方式二、方式三补充 GitHub 源安装命令\n （`install-source --source https://github.com/phoenixlucky/zerotoken-skill` /\n 「安装这个技能 https://github.com/phoenixlucky/zerotoken-skill」），\n 与 ClawHub 源并列\n- 教训固化：**发布包内的 README 以发布时工作区文件为准**——GitHub 提交 ≠\n ClawHub 包同步，README 等文档后续改动需新发版本（docs-only 可 bump patch）\n\n## [1.13.0] - 2026-08-28\n\n### Added\n- **ClawHub 发布规范**（source: v1.12.0 实测发布过程）：\n - SKILL.md 新增「📤 ClawHub 发布」章节：关键事实 + 发布陷阱表（C1-C5）+\n 固定发布时序\n - **C1**：PowerShell `curl` 是 `Invoke-WebRequest` 别名（参数不兼容），网络探测一律用 `curl.exe`\n - **C2**：`clawhub publish` 相对路径解析错误（默认 `--dir skills` 找不到根目录 SKILL.md），\n 必须传绝对路径，且先 `--dry-run` 预览\n - **C3**：发布命令上传 registry 需 5-6 分钟且全程零输出，前台运行会被超时终止，\n 必须后台运行 + 轮询等待\n - **C4**：ClawHub 安全扫描异步——提交成功（`pending security scans`）≠ 公开，\n registry 仍是旧版本号，用 `clawhub inspect` 复查\n - **C5**：发布前工作区必须干净（未提交改动会随包上传 ClawHub 但 GitHub 缺失，\n 两端分叉），发布前后各查一次 `git status`\n - 关键事实澄清：ClawHub 不是 Git 端点（`git fetch/push clawhub` 404），\n 发布必须走 clawhub CLI（pnpm 全局安装于 `%LOCALAPPDATA%\\pnpm\\clawhub.CMD`，用全路径调用）\n- README.md「📖 核心文档」索引新增 ClawHub 发布条目\n\n## [1.12.0] - 2026-08-25\n\n### Added\n- **环境识别与系统参数持久化**：新增 `scripts/detect_env.py` — 任何涉及命令行执行的\n 任务开始时先探测当前系统参数并保存到 `.zerotoken/environment.json`（7 天有效期）：\n OS 名称/版本、推荐 Shell（Windows→PowerShell，Linux→bash，macOS→zsh）、\n 控制台编码（stdout encoding + Windows ANSI/OEM 代码页）、\n **中文字符支持判定**（`console.cjk_capable`）、PowerShell 可用性/版本/发行版\n （5.1 Desktop 与 7+ Core 编码行为不同）、Git `core.quotepath` 现状\n- 新增 G 模式（POSIX 标准工作流）：detect_env.py 识别到 Linux/macOS 时自动启用，\n 使用 sh/bash/zsh 工具链，明确不套用 F 模式的 PowerShell 规避规则\n- 核心原则新增 #8「先识别环境，再选 Shell」：命令行任务第一步先获取并保存系统参数，\n 之后所有命令按已保存参数选择 Shell——**Windows 一律 PowerShell，禁用 bash**\n- `init_env.ps1` 新增 [0.5] 系统参数识别段：输出 PowerShell 版本/发行版、ANSI 代码页、\n 中文字符支持判定，并联动 `detect_env.py` 输出完整探测报告\n- `docs/unicode-encoding-spec.md` 新增「Shell 选择规则」章节：先探测系统参数再选 Shell，\n 中文支持能力以 `console.cjk_capable` 为准\n- 回归测试 `scripts/test_detect_env.py`：recommended_shell 分支、CJK 判定矩阵、\n 结构完整性、持久化 round-trip / 过期拒绝 / 损坏拒绝\n\n### Changed\n- **F 模式触发条件放宽**：由「Windows/PowerShell + 中文文本且用户确认」改为\n 「detect_env.py 识别到 Windows 系统即自动启用」，中文支持内置于环境识别结果，\n 不再要求任务涉及中文\n- SKILL.md / README.md：F 模式描述同步改写为自动识别；模式计数更新为七种（A-G）；\n 清除全部 ```` ```bash ```` 代码块标记（Windows 环境下不再展示 bash 用法）\n- 工具清单补齐：SKILL.md 脚本表与 README.md 工具集列表均加入 `detect_env.py`\n\n### Fixed\n- `detect_env.py` 时间戳格式与过期解析不一致的 bug（`detected_at` 统一为\n 紧凑格式供 `is_fresh()` 解析，另附人类可读的 `detected_at_iso`）\n- `init_env.ps1` 变量 `$psEdition` 与 PS 只读自动变量 `$PSEdition` 冲突\n （PS 变量名大小写不敏感），更名为 `$psEditionName`\n\n## [1.11.0] - 2026-08-14\n\n### Added\n- 新增陷阱 #14：PS 5.1 写方向编码不统一 — `Set-Content`/`Add-Content` 默认按 GBK\n 写出（纯汉字→GBK 字节污染 UTF-8 文件；emoji 等字符**静默写成 `?` 丢字**，\n 字节级实测为 `3F`），`Out-File` / `>` 默认 UTF-16 LE，显式 `-Encoding UTF8`\n 又带 BOM。修复方案：PowerShell 内写 UTF-8 统一用\n `[IO.File]::WriteAllText($path, $text, [Text.UTF8Encoding]::new($false))`；\n 含中文/emoji 的写入一律走 Python `safe_io.safe_write()` / `safe_append()`\n- 新增陷阱 #15：`Add-Content -Encoding UTF8` 追加到不以换行结尾的文件时**不补换行**\n 导致内容粘连（实测 `base` + 追加标题 → 粘连成一行），且带 BOM。\n 修复方案：统一改用 `safe_io.safe_append()`（自动补换行、UTF-8 无 BOM）\n- `docs/unicode-encoding-spec.md` 新增「文件写入编码矩阵（PS 5.1 实测）」：\n Set-Content / Add-Content / Out-File / WriteAllText 四种方式的默认与显式行为对照\n- `scripts/init_env.ps1` 新增第 0 步：把当前会话 `[Console]::OutputEncoding` /\n `$OutputEncoding` 切到 UTF-8（仅当前会话生效，不改系统全局设置），\n 缓解终端显示层中文乱码\n\n### Changed\n- `scripts/safe_io.py` 重构：新增 `sniff_encoding()`（BOM→UTF-8→GB18030 单一检测核心）\n 与 `decode_bytes()`；编码无法确定时显式抛 `UnknownEncodingError`，\n **移除 `errors='replace'` 静默损坏兜底**（对齐 docs 规范「禁止静默替换」；\n `strict=False` 仅限查看场景且禁止回写）。`safe_read` 保留为兼容别名，\n UTF-16/32 解码统一交由对应 codec 剥离 BOM（避免开头残留 U+FEFF）\n- `scripts/safe_io.py` `safe_append()` 修复段间粘连：目标文件存在且不以换行结尾时\n 先补换行再追加，对齐 Add-Content「每次追加自带换行」语义\n- 五个脚本的重复 `_ensure_utf8_stdio` + `sp` 副本统一收敛到\n `safe_io.ensure_utf8_stdio` / `safe_print`（batch_edit / verify_output /\n fix_encoding / detect_gbk_contamination 仅 import 复用）；\n `batch_edit.py` 删除行为分裂的本地 `safe_read`，改用统一的 `read_text`\n- 同步更新 `SKILL.md`（陷阱表 13→15 条、模式速查、不做什么、工具表）、\n `README.md`（计数引用与 F 模式描述）\n\n### Tests\n- `scripts/test_safe_io.py` 扩充为完整回归：sniff 全分支、BOM 剥离无 U+FEFF、\n unknown 抛错、strict/非 strict、safe_write/safe_append 无 BOM+LF+补换行、\n write_result 往返\n\n## [1.10.1] - 2026-08-13\n\n### Changed\n- 版本号 1.10.0 → 1.10.1\n\n### Added\n- 新增陷阱 #13：PowerShell 读取附件时中文乱码显示（Get-Content 默认按 ANSI/GBK 解码\n UTF-8 无 BOM 文件），属显示层问题、文件未损坏。修复方案：优先用 `read_file` 工具\n 读取附件；必须在 PowerShell 中读时显式 `Get-Content -Encoding UTF8`；非 UTF-8 附件\n 用 `safe_io.safe_read()` 自动检测编码；禁止把显示乱码误判为文件污染而盲目转码\n- 同步更新 `SKILL.md`（陷阱表、模式速查表、不做什么）、`README.md`（3 处引用）、\n `docs/unicode-encoding-spec.md`（读取附件/文件编码细则）\n\n## [1.10.0] - 2026-08-10\n\n### Changed\n- 版本号 1.9.1 → 1.10.0\n- 文档排版与结构规范化：修复 `SKILL.md` 未闭合代码块（「精准提示词模板」标题此前被吞进代码块）；`SKILL.md` 顶层章节标题统一 emoji 前缀（与 README 一致）；`README.md` 与 `SKILL.md` 重复的 5 个章节（尉缭子十原则、搜索资料规范、精准提示词模板、ZeroToken 强化模式、退出条件）精简为摘要 + 锚点链接，单一信息源；修复 `docs/unicode-encoding-spec.md` 死链引用\n- 搜索资料规范放宽：Chrome MCP 搜索引擎**不限百度**（百度只是默认，网络可用时 Bing / Google / 知乎等按检索效果自由选择）；Chrome MCP 不可用时允许使用当前网络可用的其他搜索方式（含 `web_fetch`），不再因首选方案不可用而放弃搜索。同步更新 `README.md`、`SKILL.md`\n- 落地「Unicode 安全编码规范」（新增 `docs/unicode-encoding-spec.md`，15 条硬性规定 + 项目执行细则；AGENTS.md 增加编码规范约束）\n- 所有 Python 脚本：控制台输出优先 `sys.stdout.reconfigure(encoding='utf-8')`（Python 3.7+），不再把中文替换成 `?`；写模式 `open()` 显式 `newline='\\n'`，避免 Windows 文本模式把 LF 写成 CRLF\n- `scripts/batch_edit.py` / `scripts/verify_output.py`：去除 `errors='replace'` 静默损坏，非 UTF-8/UTF-16/GB18030 文件显式抛错提示先检查原编码\n- `scripts/init_env.ps1` 转为 UTF-8 with BOM（Windows PowerShell 5.1 解析中文必需）；清理未使用变量\n- `.reasonix/skills/mcp-streamable-connect/mcp-bridge.js`：HTTP `Content-Type` 显式声明 `charset=utf-8`\n- SKILL.md「安全文件读写模板」更新（写/追加显式 `newline='\\n'`），替换字符示例改为文字描述（U+FFFD）\n\n### Added\n- 新增 `scripts/audit_encoding.py` 全项目编码审计工具（UTF-8 / BOM / 替换字符 / 混合换行检测）\n\n## [1.9.1] - 2026-08-08\n\n### Changed\n- 版本号 1.9.0 → 1.9.1\n\n## [1.9.0] - 2026-08-07\n\n### Added\n- SKILL.md 核心原则之后新增「AI 编程总纲（尉缭子十原则）」章节 — 以《尉缭子》兵法治编程纪律：先谋后动、统一方案、职责明确、不得越权、唯一命令、禁止旧令、严格执行、最小改动、可追溯、验证先于结束\n- 十原则以「原则 + 要求 + 违反示例」表格精炼呈现，并给出与 B/C/E 任务模式的对应关系及可直接用作 System Prompt 的总纲引文\n- 核心理念：省 token 是效率（ZeroToken），尉缭子是秩序（权限边界、单一指令、责任明确、执行一致）\n\n## [1.8.2] - 2026-07-24\n\n### Added\n- 新增陷阱 #10-#12：PowerShell `&&` 不兼容、内联 `python -c` SyntaxError、终端显示层中文乱码\n- 核心原则第3条补充大文件分页读取规则\n- 核心原则第6条补充 `complete_step` 证据类型规则（files/manual/verification 用法 + 单步签收）\n- 「不做什么」新增 3 条禁用规则\n\n## [1.8.1] - 2026-07-24\n\n### Added\n- 增强搜索规范：新增「Chrome MCP 能搜什么」场景表，消除 AI 不知道 Chrome MCP 能搜微博/新闻等的问题\n- 新增「禁用行为」三项硬约束：禁 web_fetch 直抓社交平台、禁自写 playwright 脚本、禁 web_fetch 直连搜索引擎\n\n## [1.8.0] - 2026-07-?? (unreleased)\n\n### Added\n- 适配 browser-localmcp-skills：新增 mcp_call.py Python 包装脚本，彻底规避 Windows PowerShell 引号嵌套和 GBK 编码崩溃问题\n- SKILL.md 新增「搜索资料指南」章节，明确 Chrome MCP 优先搜索策略\n- SKILL.md 全量示例迁移至 mcp_call.py，消除 Windows 平台调用屏障\n\n### Fixed\n- 规避「Bing 搜索返回无关结果」问题，强制优先走 Chrome MCP（百度搜索）\n\n## [1.7.2] - 2026-07-22\n\n### Fixed\n- 重新发布 v1.7.2 以修复 ClawHub 版本列表未更新的问题（前版 publish 成功但未写入数据库）\n- 内容与 v1.7.0 一致\n\n## [1.7.1] - 2026-07-22\n\n### Fixed\n- 重新发布以刷新 ClawHub 页面展示版本（技术性 bump，内容与 v1.7.0 一致）\n\n## [1.7.0] - 2026-07-21\n\n### Security\n- **Tp4 (MCP Tool Poisoning)** — 重写 SKILL.md `description` frontmatter，从纯\"token-efficient discipline\"扩展为同时声明文件系统工具能力的透明描述。\n- **Language Policy Opt-in** — 添加 `language_opt_in: true` metadata；H1 下方新增语言选择提示，明确中文引导为 opt-in；`agents/openai.yaml` 的 `default_prompt` 添加 opt-in 前缀。\n- 新增 `language_opt_in` metadata 字段至 SKILL.md frontmatter，供主机/审计工具检测。\n\n### Added\n- `agents/openai.yaml` 的 `short_description` 改为英文描述 + opt-in 说明。\n- `scripts/safe_io.py`: 新增 `safe_append(path, content)` 函数 — 使用 Python `open(path, 'a', encoding='utf-8')` 替代 PowerShell `Add-Content`，防止 GBK 编码污染 UTF-8 文件\n- `scripts/detect_gbk_contamination.py`: 新增检测和修复 UTF-8 文件中 GBK 编码污染的独立脚本（三种模式：`scan` 扫描目录检测污染文件、`inspect` 详细查看污染位置和字节上下文、`fix` 智能修复污染并支持 `--backup` 备份和 `--preview` 预览）\n- SKILL.md F 模式：新增陷阱 #8（PowerShell Add-Content GBK 编码污染），脚本工具表新增 `detect_gbk_contamination.py` 条目并更新 `safe_io.py` 条目，安全文件读写模板增加安全追加示例，\"不做什么\"清单增加 Add-Content 禁令\n- `scripts/init_env.ps1`: 脚本工具提示中加入 `detect_gbk_contamination.py` 条目并更新 `safe_io.py` 描述\n\n## [1.6.2] - 2026-07-10\n\n### Security\n- Removed hardcoded git commit permission from `reasonix.toml` — replaced with generic tool permissions (Bash, Read, Edit, Write) to eliminate appearance of hidden repository-modifying intent.\n- Changed `scripts/init_env.ps1` Git quotepath from `--global` to local scope (removed `--global` flag); removed unnecessary `core.autocrlf` setting.\n- Updated SKILL.md security disclosure to explicitly address `reasonix.toml` permission declarations and `init_env.ps1` local-only scope.\n\n## [1.6.1] - 2026-07-10\n\n### Security\n- Added `security` metadata to SKILL.md frontmatter — explicitly declares all file system capabilities (read/write, batch-edit, encoding-conversion, git-operations) so users and hosts can review before installation.\n- Added \"🛡️ 能力与安全披露\" (Capabilities & Security Disclosure) section to SKILL.md — transparently documents what the skill can do beyond prompting guidance.\n- Clarified F mode (Windows/PowerShell) is conditional and optional, not default behavior — macOS/Linux users and English-only workflows do not need it.\n- Added language disclosure: documentation is primarily in Chinese but the skill adapts to the user's interaction language.\n- Fixed `scripts/fix_encoding.py` docstring: changed \"默认创建 .bak 备份\" to \"需要 --backup 参数才会创建 .bak 备份\" to match actual implementation behavior.\n\n## [1.6.0] - 2026-07-10\n\n### Added\n- Added `scripts/` directory with 4 Python utility scripts + 1 PowerShell init script:\n - `scripts/safe_io.py` — safe file read/write module (handles UTF-8/UTF-16, write-to-file instead of print)\n - `scripts/fix_encoding.py` — batch file encoding detection and conversion to UTF-8 (4 modes: scan/preview/convert/check-replacement)\n - `scripts/verify_output.py` — verification result output to .txt file (replaces print to avoid GBK error)\n - `scripts/batch_edit.py` — apply multiple replacements to one file atomically (solves edit_file consecutive edit blocking)\n - `scripts/init_env.ps1` — Windows PowerShell environment init (git config, Python check, encoding health)\n- Added `.gitattributes` — proper line ending configuration for all file types\n- Updated SKILL.md F mode: references scripts/ tools in decision table and recommended workflow; adds \"脚本工具\" reference table\n\n## [1.5.0] - 2026-07-10\n\n### Added\n- Added **F. Windows/PowerShell 环境适配** task mode to SKILL.md for handling Windows PowerShell + Chinese text environment pitfalls — includes 7 known trap solutions, recommended workflow, safe file I/O template, and \"what not to do\" checklist.\n\n## [1.4.0] - 2026-04-27\n\n### Added\n- Added **E. 重大重构/架构调整** task mode to SKILL.md for handling systemic bugs, architecture mismatches, and large-scale refactoring — includes 5 trigger signals, 6-step flow (diagnosis → impact assessment → user-confirmed design → incremental migration → verified execution → cleanup), and dedicated output format.\n\n## [1.3.0] - 2026-04-27\n\n### Changed\n- Deduplicated README.md by removing content replicated from SKILL.md; README now serves as a slim landing page.\n- Trimmed package.json keywords from 24 to 7 (removed synonyms and sub-variants).\n- Shortened SKILL.md frontmatter description for clarity.\n- Relicensed from MIT to GPL-3.0 (copyleft license for stronger openness).\n\n### Fixed\n- Removed duplicate \"Added LICENSE\" entry from [1.1.0] in CHANGELOG.md — LICENSE was first added in v1.2.0.\n\n## [1.2.0] - 2026-04-27\n\n### Added\n- Added about description and topic tags to GitHub repository.\n- Added LICENSE file (MIT) to complete open source compliance.\n\n## [1.1.0] - 2026-04-27\n\n### Added\n- Added quick decision table mapping user request patterns → task mode → output format → tool preference.\n- Added \"精准提示词模板\" (precise prompt template) with compact goal/input/constraints/output format.\n- Added \"ZeroToken 强化模式\" section for explicit token-saving requests.\n- Added \"何时不使用 ZeroToken\" guard section.\n\n### Changed\n- Restructured SKILL.md: decision table at top, then core principles (5 from 8), then task modes with concrete tool mappings.\n- Tightened all sections—removed redundancy across core principles, task modes, and output rules.\n- Updated agents/openai.yaml default_prompt to match new decision-table-first flow.\n\n## [1.0.3] - 2026-04-27\n\n### Changed\n- Expanded package keywords for prompt engineering, context optimization, token budgeting, and agent workflow discovery.\n\n## [1.0.2] - 2026-04-27\n\n### Added\n- Added guidance for crafting the shortest precise prompt needed to solve the user's problem.\n- Added prompt framing rules for goal, input, constraints, output format, and acceptance criteria.\n\n## [1.0.1] - 2026-04-27\n\n### Changed\n- Changed the skill trigger guidance so ZeroToken is the default working discipline for suitable tasks.\n- Documented exceptions for exhaustive explanation, teaching-style expansion, brainstorming, and broad exploration.\n\n## [1.0.0] - 2026-04-27\n\n### Added\n- Added the initial `SKILL.md` with ZeroToken working discipline for token-efficient task execution.\n- Added `agents/openai.yaml` with a host-facing ZeroToken prompt preset.\n- Added minimal publishing files: `package.json`, `README.md`, and `CHANGELOG.md`.\n\nFile v1.17.0:docs/unicode-encoding-spec.md\n\n# Unicode 安全编码规范（项目执行版）\n\n> 本文件是「Unicode 安全编码规范」在本仓库的执行细则。\n> 生成或修改任何代码、配置、文档时，必须遵守本规范。\n> 配套工具见 `scripts/` 目录；仓库历史问题与根因见 `references/windows-powershell.md` 的「已知陷阱与解决方案」。\n\n## 总目标\n\n> 内部统一使用 Unicode，外部文本数据统一优先使用 UTF-8，\n> 所有编码边界显式声明编码，不依赖默认字符集，不进行无意义的重复转码。\n\n## 硬性规定（15 条）\n\n1. 所有源码、配置文件、模板文件、JSON、CSV、日志和文本文件统一使用 UTF-8 编码。\n2. 不要依赖操作系统、IDE、运行环境或系统区域设置的默认字符集。\n3. 任何涉及字符串、文件、网络请求、HTTP、数据库、JSON 序列化/反序列化的地方，都必须明确使用 UTF-8。\n4. 禁止在没有明确需求的情况下使用 GBK、GB2312、ANSI、Latin-1、Windows-1252 等编码。\n5. 禁止出现 UTF-8 编码后再按 GBK、ANSI 或其他编码解码的情况。\n6. 文件读取和写入时，应显式指定 UTF-8，而不是使用默认编码。\n7. Web 页面统一声明 UTF-8，例如：``\n8. HTTP 接口涉及文本内容时，应正确声明 UTF-8，例如：`Content-Type: application/json; charset=utf-8`\n9. 数据库应优先使用支持完整 Unicode 的字符集，例如 MySQL 使用 `utf8mb4`，同时确保数据库、表、字段和连接字符集保持一致。\n10. JSON 中的中文应正常作为 Unicode 字符处理，不要为了「防止乱码」而进行不必要的重复转码。\n11. 不要对已经是 Unicode 字符串的数据重复执行 encode/decode。\n12. 如果代码中存在 Base64、URL Encoding、HTML Entity、Unicode Escape 等编码操作，要明确区分「字符编码」和「数据转义」，不要混用。\n13. 修改已有项目时，先检查原有编码方式，避免因为强制转换造成已有数据损坏。\n14. 如果无法确定外部输入的字符编码，不要猜测，应在代码中增加明确的编码检测、参数配置或异常处理。\n15. 中文字符串、中文注释、中文文件名和中文接口数据都必须能够正确读取、存储、传输和显示。\n\n## Shell 选择规则（先探测系统参数）\n\n- 任何涉及命令行执行的任务，第一步先运行 `python scripts/detect_env.py`\n 获取当前系统参数并保存到 `.zerotoken/environment.json`（7 天有效期）。\n- **Windows 系统**一律使用 PowerShell 语法（`;` 链式 / `if ($?) {}` 条件链式），\n **禁用 bash**；PowerShell 版本以保存的探测结果为准\n （5.1 Desktop 与 7+ Core 的编码默认行为不同）。\n- **Linux/macOS** 使用 sh/bash/zsh 等 POSIX shell，不套用 PowerShell 规避规则。\n- 中文支持能力以探测结果 `console.cjk_capable` 为准：不支持时内容验证走文件而非终端显示。\n\n## 编码链路检查\n\n生成代码前，检查整个字符处理链路，确保每一个环节的编码一致：\n\n```\n输入数据 → 字符串处理 → 文件/数据库 → 网络传输 → API → 前端/终端显示\n```\n\n## 项目执行细则\n\n### Python 文件读写\n\n- 所有 `open()` 必须显式指定编码：读取用 `open(path, 'rb')` 二进制读后显式 decode，\n 或 `open(path, 'r', encoding='utf-8')`；写入一律 `open(path, 'w', encoding='utf-8')`。\n- **禁止** `errors='replace'` 静默替换损坏字符（会把中文无声变成 U+FFFD 替换字符）。\n 编码无法确定时必须显式抛错提示先检查原编码：\n 统一实现见 `scripts/safe_io.py` 的 `sniff_encoding` / `decode_bytes`\n （BOM → UTF-8 → GB18030，全部失败抛 `UnknownEncodingError`）。\n- 读取历史遗留文件（可能为 UTF-16 或 GB18030）用 `scripts/safe_io.py` 的 `safe_read`，\n 它会自动检测 BOM 并做安全解码；写入统一 UTF-8 无 BOM（`safe_write` / `safe_append`）。\n\n### 控制台输出（Windows 中文环境）\n\n- Python 3.7+：模块加载时显式 `sys.stdout.reconfigure(encoding='utf-8')`\n （`sys.stderr` 同理），不要依赖系统代码页（中文 Windows 默认 GBK/936）。\n- 兜底：无法重配置的流用 `safe_print`（`scripts/safe_io.py`），保证永不抛\n `UnicodeEncodeError`。\n- 终端显示：PowerShell 中配合 `chcp 65001` 查看中文输出；若仍乱码，属于终端显示层\n 问题，文件本身编码正确，用 `read_file` 工具验证内容。\n- **读取附件/文件**：Windows PowerShell 5.1 的 `Get-Content` 默认按 ANSI 代码页（GBK）\n 解码无 BOM 的 UTF-8 文件，含中文的附件会**显示乱码**（如 `鐗堟湰鍙?1.9.1`），但文件\n 未损坏。优先用 `read_file` 工具读取；必须在 PowerShell 中读时显式指定\n `Get-Content -Encoding UTF8`；附件是 GBK/UTF-16 等非 UTF-8 编码时用\n `safe_io.safe_read()` 自动检测转码。显示乱码≠文件损坏，禁止据此盲目转码。\n- **禁止**用 PowerShell `Add-Content` 向 UTF-8 文件追加中文（默认 GBK 写入会污染），\n 改用 Python `open(path, 'a', encoding='utf-8')` 或 `safe_io.safe_append`。\n\n### 文件写入编码矩阵（PS 5.1 实测）\n\n| 写入方式 | 默认编码 | 显式 `-Encoding UTF8` | 结论 |\n|----------|----------|----------------------|------|\n| `Set-Content` | GBK/ANSI；非 GBK 字符**静默写成 `?`**（emoji 实测变 `3F`） | UTF-8 **带 BOM** | ❌ 禁止用于任何非 ASCII 内容 |\n| `Add-Content` | 同上（追加即污染 UTF-8 文件）；且目标不以换行结尾时**不补换行导致粘连** | 带 BOM + 同样不补换行 | ❌ 禁止追加中文，统一用 `safe_io.safe_append()` |\n| `Out-File` / `>` 重定向 | UTF-16 LE（带 BOM） | UTF-8 带 BOM | ⚠️ 非 ASCII 时禁用默认行为 |\n| `[IO.File]::WriteAllText` / `AppendAllText` | **UTF-8 无 BOM**（.NET Core 3.0+/PS7 默认；5.1 下建议显式传编码） | — | ✅ PowerShell 内首选 |\n\n- PowerShell 中确需直接写 UTF-8 文本时统一用：\n `[IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`。\n- 跨脚本、含中文/emoji 的写入一律走 Python：`safe_io.safe_write()`（UTF-8 无 BOM +\n LF）/ `safe_append()`（自动补换行）。\n\n### PowerShell 脚本（.ps1）\n\n- **唯一例外**：`.ps1` 文件必须使用 **UTF-8 with BOM**。\n 原因：Windows PowerShell 5.1（系统自带）对无 BOM 文件按 ANSI 代码页（GBK）解码，\n 含中文的 UTF-8 无 BOM 脚本会乱码甚至解析异常。\n PowerShell 7+ 无此问题，但为兼容 5.1 统一带 BOM。\n- 已由 `scripts/init_env.ps1` 示范（首字节 `EF BB BF`）。\n\n### Node.js / HTTP\n\n- 请求头/响应头显式声明编码，例如\n `'Content-Type': 'application/json; charset=utf-8'`。\n- `fetch` / `readFileSync` / `writeFileSync` 显式传 `'utf-8'`；`JSON.stringify` 默认\n 保留 Unicode（不要 `escape` 转义中文）。\n- URL 编码、Base64、HTML Entity 属于**数据转义**，与字符编码无关，不得混用。\n\n### JSON\n\n- 中文作为普通 Unicode 字符处理：Python 用 `json.dumps(data, ensure_ascii=False)`，\n 写入文件时 `encoding='utf-8'`；不要为了「防乱码」做重复转码。\n\n### 数据库\n\n- 如引入数据库，使用 `utf8mb4`，并确保数据库、表、字段、连接字符集一致。\n\n## 仓库现有工具链\n\n| 工具 | 用途 |\n|------|------|\n| `scripts/safe_io.py` | 编码检测核心（sniff_encoding/decode_bytes）+ 安全读写（read_text/safe_read/safe_write/safe_append/write_result），safe_print 控制台兜底；unknown 显式抛 UnknownEncodingError |\n| `scripts/fix_encoding.py` | 扫描/转换文件编码为 UTF-8（scan / preview / convert / check-replacement） |\n| `scripts/detect_gbk_contamination.py` | 检测并修复 UTF-8 文件中的 GBK 污染（scan / inspect / fix） |\n| `scripts/batch_edit.py` | 一次多编辑（原子替换），复用 safe_io.read_text，不静默损坏 |\n| `scripts/verify_output.py` | 验证结果写入 UTF-8 文件（替代 print），grep_check 显式解码 |\n| `scripts/audit_encoding.py` | 全项目编码审计（UTF-8/BOM/替换字符/混合换行） |\n| `scripts/detect_env.py` | 环境探测与持久化：OS / Shell / 控制台编码 / 中文支持 / PowerShell 版本 / Git quotepath，结果存 `.zerotoken/environment.json`（7 天有效期），决定 F/G 模式与 Shell 选择 |\n| `scripts/init_env.ps1` | Windows 环境初始化（git quotepath、控制台 UTF-8、编码健康检查） |\n\n## 生成代码后的安全检查\n\n每次生成/修改代码后，额外执行一次：\n\n```powershell\npython scripts/audit_encoding.py --root . --out audit_result.txt\n```\n\n确认：\n1. 无 `non-utf8` 文件；\n2. 无 `替换字符`（U+FFFD）；\n3. 无混合换行（LF/CRLF 混用）；\n4. `.ps1` 文件带 BOM（审计单独列 `utf-8-sig` 属预期）。\n\nFile v1.17.0:skill-card.md\n\n## Description:\n\nZeroToken guides agents toward concise, token-efficient task execution and includes optional utilities for environment detection, UTF-8-safe file handling, encoding conversion, and Windows PowerShell workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[phoenixlucky](https://clawhub.ai/user/phoenixlucky)\n\n### License/Terms of Use:\n\nGPL-3.0\n\n## Use Case:\n\nDevelopers and agent users use ZeroToken to make assistants choose the right task mode, limit unnecessary context, produce concise answers, and apply platform-aware file and shell workflows when needed.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: File and encoding utilities can modify project files or overwrite conversion targets.\n\nMitigation: Review generated commands before execution, use preview or backup modes for conversion and repair workflows, and run the bundled checks after changes.\n\nRisk: Local helper scripts and environment detection can create workspace state or adjust current-repository Git display settings on Windows.\n\nMitigation: Install only when the concise-output and encoding workflow is desired, run utilities in trusted workspaces, and inspect repository-local configuration changes.\n\nRisk: External search tasks may send query terms to third-party search or browser services.\n\nMitigation: Avoid external search for sensitive or non-public project details unless the user has confirmed the disclosure.\n\n## Reference(s):\n\n- [ZeroToken Skill](SKILL.md)\n- [README](README.md)\n- [Unicode Safety Encoding Specification](docs/unicode-encoding-spec.md)\n- [Windows / PowerShell Environment Adaptation](references/windows-powershell.md)\n- [Major Refactor / Architecture Adjustment Playbook](references/refactor-playbook.md)\n- [External Search Guidelines](references/search.md)\n- [Tool Mapping and Host-Specific Behavior](references/tool-mapping.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration]\n\n**Output Format:** [Markdown guidance with inline commands, code snippets, and configuration examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Concise, task-mode-driven output; language follows the user's interaction language.]\n\n## Skill Version(s):\n\n1.17.0 (source: frontmatter, package.json, CHANGELOG, ClawHub release)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.16.0: 33 files, 270458 bytes\n\nFiles: AGENTS.md (2718b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (165378b), CHANGELOG.md (24706b), docs/unicode-encoding-spec.md (8968b), LICENSE (35792b), package.json (918b), README.md (10632b), references/publishing-clawhub.md (3690b), references/refactor-playbook.md (2756b), references/search.md (2770b), references/tool-mapping.md (3102b), references/windows-powershell.md (13292b), scripts/audit_encoding.py (6214b), scripts/audit_skill.py (14209b), scripts/batch_edit.py (3690b), scripts/bump_version.py (4679b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_audit_encoding.py (1806b), scripts/test_audit_skill.py (3348b), scripts/test_bump_version.py (3512b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/test_zt.py (2162b), scripts/verify_output.py (5081b), scripts/zt.py (9791b), skill-card.md (2564b), SKILL.md (12194b), _meta.json (135b)\n\nFile v1.16.0:SKILL.md\n\n---\nname: zerotoken-skill\nversion: 1.16.0\ndescription: Token-efficient assistant discipline for concise, direct answers and minimal-context task execution. Use when the user asks for low-token / direct output or says「省 token / 简洁点 / 直接给结果 / 少废话 / 别解释」, or invokes this skill; includes optional file-encoding and Windows PowerShell utilities (single entry: `python scripts/zt.py help`).\nmetadata:\n security:\n capabilities:\n - filesystem-read: \"read local files\"\n - filesystem-write: \"write/modify local files\"\n - batch-edit: \"apply multiple text replacements to a single file\"\n - encoding-conversion: \"batch file encoding detection and conversion\"\n - gbk-contamination-detection: \"detect and repair GBK-contaminated UTF-8 files\"\n - git-operations: \"git config and commit operations\"\n permissions-declared: true\n language: \"回答语言跟随用户交互语言（用中文问就中文答）；文档正文为 zh-CN\"\n platforms: \"auto-detects OS at session start (detect_env.py): Windows/PowerShell -> Mode F, Linux/macOS -> Mode G\"\n references: \"细节按需读取 references/*.md（Windows 陷阱 / 重构手册 / 搜索规范 / 发布手册 / 工具映射）\"\n---\n\n# ZeroToken Skill\n\n> **语言**：回答语言跟随用户交互语言——用中文问就用中文答，用英文问就用英文答。\n> 平台环境由 `python scripts/detect_env.py` 自动识别，不需要用户声明语言或平台。\n> *(Answer in the user's language; environment detection is automatic.)*\n\n用最少必要 token 和最精准提示词完成任务。省 token ≠ 偷工减料；核心是减少无效上下文、无效解释、无效工具调用、无效输出。\n\n> **🛡️ 能力与安全披露**（安装前请确认符合你的安全策略）\n> 除提示词纪律外，本 Skill 还声明这些文件系统能力：\n> 读取/修改本地文件（`read_file`/`edit_file`/`write_file`）；批量替换与编码转换\n> （`scripts/batch_edit.py`、`fix_encoding.py`）；安全读写与追加（`scripts/safe_io.py`，\n> 规避 `Add-Content` 的 GBK 污染）；GBK 污染检测修复（`scripts/detect_gbk_contamination.py`）；\n> Git 配置（`scripts/init_env.ps1` 只改**当前仓库 local 配置**，不动全局）；\n> 环境探测结果写 `.zerotoken/environment.json`（7 天有效期，已 gitignore）。\n\n---\n\n## 📐 快速决策表\n\n| 用户请求特征 | 模式 | 首轮输出 | 工具偏好 |\n|---|---|---|---|\n| 问定义/翻译/短建议 | **A. 简单问答** | 1-5 句直接回答 | 直接输出，不跑工具 |\n| 单文件修复/配置调整 | **B. 代码小改** | 改动 + 验证结果 | `grep` → `read_file`(局部) → `edit_file` |\n| 跨模块功能/常规重构/CI | **C. 多文件任务** | 3-5 步短计划 | `glob` → `grep` → 分批 `read_file` |\n| 长文/日志/PR/文档总结 | **D. 大资料总结** | 要点 + 证据位置 | `read_file`(head+tail) → `grep`(关键行) |\n| 反复出同类 bug / 加功能越来越难 / 架构与需求不匹配 | **E. 重大重构/架构调整** | 问题诊断 + 目标方案 + 迁移路线图 | `explore` → 分批 `read_file`（详见 [`references/refactor-playbook.md`](references/refactor-playbook.md)） |\n| 用户明确说\"省 token\" | **ZeroToken 强化** | 最短可执行输出 | 同上，但跳过所有非必要探索 |\n| 用户说\"详细解释/教学\" | **➡ 退出 ZeroToken** | 常规详尽模式 | 不限 |\n| 系统是 Windows/PowerShell（detect_env.py 自动识别） | **F. Windows/PowerShell 环境适配** | 系统参数已保存，按陷阱规则调整工作流 | 详见 [`references/windows-powershell.md`](references/windows-powershell.md) |\n| 系统是 Linux/macOS（detect_env.py 自动识别） | **G. POSIX 标准工作流** | 按 POSIX 规则工作，禁用 PowerShell 语法 | 常规 shell 工具链（sh/bash/zsh） |\n\n> 工具名以当前宿主实际提供的为准；名字不同时见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n\n---\n\n## 🧭 核心原则\n\n1. **先分类，再预算** — 按上表决定上下文深度，不默认全量读取。\n2. **压缩提示词** — 目标 + 已知输入 + 约束 + 验收格式；只在缺失项会改变结果时追问。\n3. **渐进读取** — 先定位（`grep`/`glob`），再局部读，读完即停。大文件（70KB+）用 `read_file` 的 `offset` + `limit` 分页，避免被截断。\n4. **先给结果** — 结论或完成状态先行；解释、推理按需补充。\n5. **不复述** — 不重复用户问题、不写礼貌铺垫、不解释常识。\n6. **plan 只写顶层步骤，不写子 bullet** — 每个 phase 写 1 行（共 2-5 个），细节放说明文字里。宿主把 bullet 注册成独立待办时的规避细节、签收证据规则见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n7. **设置停止条件** — 已定位目标、必要调用方/数据源和验证方式后停止搜索；同一文件未变化时不重复读取。\n8. **先识别环境，再选 Shell** — 任何涉及命令行执行的任务，第一步：\n `python scripts/detect_env.py` → `.zerotoken/environment.json`（7 天有效期）。\n 之后所有命令按已保存的系统参数选择：Windows 一律 PowerShell（禁用 bash），\n Linux/macOS 用 sh/bash/zsh；中文支持能力以 `console.cjk_capable` 为准。\n\n---\n\n## 📚 参考文档（按需读取）\n\n| 文档 | 何时读 |\n|---|---|\n| [`windows-powershell.md`](references/windows-powershell.md) | 命中 F 模式；编码/乱码/GBK/PowerShell/附件读取问题 |\n| [`refactor-playbook.md`](references/refactor-playbook.md) | 命中 E 模式：诊断 → 方案 → 增量迁移 |\n| [`search.md`](references/search.md) | 需要外部资料、浏览器搜索、社交平台内容 |\n| [`tool-mapping.md`](references/tool-mapping.md) | 工具名与本文不符；宿主有 plan/待办/签收机制 |\n| [`publishing-clawhub.md`](references/publishing-clawhub.md) | **仅维护者**：发布新版本到 ClawHub |\n\n> 🔧 **工具入口：** `python scripts/zt.py help`（`zt.py check` 一键跑完全部校验）\n\n### 🚨 Windows 三条致命项（必守）\n\n1. **别用 `Add-Content` / `Set-Content` 写中文** — PS 5.1 默认按 GBK 写出，emoji 会静默变 `?`；改用 `safe_io.safe_write()` / `safe_append()`。\n2. **`Get-Content` 的中文乱码多是显示层假乱码** — 文件没坏；改用 `read_file` 或 `-Encoding UTF8`，禁止据乱码盲目转码重写。\n3. **命令行不内联中文**（`python -c \"中文\"`、含 `+`/反引号的参数）— 写 `.py` 脚本再 `python \"script.py\"` 执行。\n\n---\n\n## 📝 精准提示词模板\n\n```text\n目标：<要解决什么>\n输入：<数据/代码/错误/位置>\n约束：<不能做什么/必须满足什么>\n输出：<格式/字段/长度/验收标准>\n预算：<直接回答 / 最小读取 / 需要验证>（可省略，默认最小读取）\n```\n\n请求含糊时先用此模板提炼；只有缺关键输入才追问，一次只问 1 个问题。\n\n---\n\n## ⚔️ AI 编程总纲（尉缭子十原则）\n\n> **将军受命，君必先谋于庙，行令于廷，君身以斧钺授将。曰：左、右、中军皆有分职；若逾分而上请者死；军无二令，二令者诛；留令者诛；失令者诛。**\n\n核心不是军事，而是 **权限边界、单一指令、责任明确、执行一致**。与 ZeroToken 纪律互补：省 token 是效率，尉缭子是秩序。\n\n| # | 原则 | 要求 | 违反示例 |\n|---|---|---|---|\n| 1 | **先谋后动（谋于庙）** | 编码前先理解需求、明确目标、列出约束与方案，确认后再实现 | 边思考边改大量代码 |\n| 2 | **统一方案（行令于廷）** | 全仓库统一架构/命名/目录/接口/风格 | 一个问题多个实现、新旧逻辑混用 |\n| 3 | **职责明确（分职）** | 每层各司其职（UI→Service→Repository→DB），不得越级 | UI 直连数据库 |\n| 4 | **不得越权（逾分请者）** | 只改自己职责范围；修 SQL 不顺手改页面/接口/重构 | 顺手重构整个系统 |\n| 5 | **唯一命令（军无二令）** | 任何时刻只有一个最终需求；新需求先确认：废弃/覆盖/追加原需求 | 同时执行互相冲突的需求 |\n| 6 | **禁止旧令（留令者）** | 需求更新后旧方案立即失效，删除/替换/迁移，不留兼容层 | \"为了兼容以前\"偷偷保留旧代码 |\n| 7 | **严格执行（失令者）** | 已确认要求全部落实：功能/性能/注释/测试/边界情况 | 遗漏边界情况 |\n| 8 | **最小改动** | 修改范围越小越好，不影响已有功能；每次提交只解决一个问题 | 无关优化/重构 |\n| 9 | **可追溯** | 每次修改说明：为什么改、改了哪些文件/函数、影响、如何验证 | 修改历史无法追踪 |\n| 10 | **验证先于结束** | 编译/运行/需求/边界/回归全部验证通过才宣布完成 | 编码完就宣布结束 |\n\n**与任务模式的对应**：E 模式内置 #1（先诊断方案）、#8（不提前优化）、#10（每步验证）；\nB/C 模式动手前一句话确认需求 = #5；输出格式的「改动 / 验证 / 注意」= #9 + #10。\n\n### System Prompt 总纲\n\n> 臣缭以为：AI 编程，当先谋后动，后行其令。未明需求，不得编码；未定方案，不得实现。各模块各司其职，不得越权修改；一事唯遵一令，不得两令并行；新令既下，旧令即废，不得留存；既受其令，不得遗漏，不得擅改，不得借机重构。每次修改，应最小影响、责任明确、过程可追溯、结果可验证。凡编码者，以稳定为本，以一致为法，以执行为先。\n\n---\n\n## 🔄 任务模式要点\n\n- **A. 简单问答**：直接回答，不列计划、不问澄清（除非缺关键对象），不主动扩展背景。\n- **B. 代码小改**：定位 → 只读命中行附近 → 精准改 → 跑最小相关验证（lint / typecheck / 单测）。\n- **C. 多文件任务**：3-5 步短计划（每步 1 行，不用 bullet 子步骤）→ 每步只加载当前决策需要的文件 →\n 非关键问题记为事实清单而非当场修复 → 最终只报完成内容、关键改动、验证结果。\n- **D. 大资料总结**：先定输出目标（摘要/决策/风险/待办/差异/时间线）→ 保留数字、日期、结论、阻塞点 →\n 「要点 + 证据位置」代替大段引用。\n- **E. 重大重构**：见 [`refactor-playbook.md`](references/refactor-playbook.md)（先确认方案，再增量迁移）。\n- **F. Windows/PowerShell**：见 [`windows-powershell.md`](references/windows-powershell.md)（15 条陷阱 + 脚本工具）。\n- **G. POSIX**：sh/bash（macOS 默认 zsh），不套用 F 模式规则；文件编码仍统一 UTF-8\n （见 `docs/unicode-encoding-spec.md`）；非 UTF-8 locale 下中文可能显示乱码，验证走文件而非终端。\n\n---\n\n## ⚡ ZeroToken 强化模式\n\n当用户明确要求省 token / 简洁 / 减少上下文时，在对应模式基础上额外：\n\n- 跳过所有非必要探索（不 glob 全目录、不预览多个候选）\n- 工具调用次数压到最低（能 1 步不用 2 步）\n- 每次读取或工具调用前写明要验证的假设；得到答案即停止，不为\"保险\"重复调用\n- 输出只保留：做了什么 + 结果 + 用户下一步需要的操作（如果有）\n\n## 📤 输出格式\n\n```text\n已完成：...\n改动：...\n验证：...\n注意：... ← 无风险时省略\n```\n\n研究类：\n\n```text\n结论：...\n依据：...\n不确定：...\n下一步：...\n```\n\n重构/架构类（E 模式）的输出模板见 [`references/refactor-playbook.md`](references/refactor-playbook.md)。\n\n## 🚫 何时不使用 ZeroToken\n\n- 用户明确要求：详细解释、教学式展开、头脑风暴、广泛探索\n- 任务涉及：法律、医疗、金融决策、时间敏感信息（准确性优先，不省 token）\n- 用户明确说\"请详细说明\"\n\n## 🛡️ 质量底线\n\n- 不省略安全、准确性和用户明确要求\n- 不跳过必要测试来制造\"省 token\"假象\n- 不把猜测写成事实\n- 不用短答案掩盖不确定性\n\nFile v1.16.0:README.md\n\n\n\n# ⚡ ZeroToken Skill\n\n**让 Agent 用最少的 token 做最准的事**\n\n> ⚔️ **先谋后动，军无二令 —— 省 token 是效率，尉缭子是秩序。**\n>\n> 💬 **用不完，根本用不完，妈妈再也不用担心我缺 token 了。**\n\n[]()\n[](LICENSE)\n[]()\n[](https://github.com/phoenixlucky/zerotoken-skill/actions/workflows/ci.yml)\n\n
\n\n> **ZeroToken Skill** 是一套为 AI Agent 设计的**提示词纪律规范**——在不降低回答准确性的前提下，压缩无效上下文、无效解释、无效工具调用和无效输出。\n>\n> 它解决的核心问题是：Agent 在任务中经常过度读取、过度思考、过度输出，导致一次对话消耗成千上万不必要的 token。本 Skill 通过一套可执行的**模式决策表 + 行为约束 + 工具链策略**，让 Agent 在每一个任务环节都有明确的\"省 token 行为准则\"。\n>\n> 🎯 **目标：** 用最精准的提示，做最少的往返，产最精炼的结果。\n>\n> ✅ **适用于：** Reasonix / Codex CLI / OpenCode / Hermes / Cline 等主流 Agent 工具。一次学习，全平台受益。\n\n\n\n
\n\n
\n\n**⚡ 少即是多 — Less is More**\n\n
\n\nFile v1.16.0:_meta.json\n\n{\n \"ownerId\": \"kn7dpzpqn086by5pfg5sbf64zx80zr6m\",\n \"slug\": \"zerotoken-skill\",\n \"version\": \"1.16.0\",\n \"publishedAt\": 1789882946932\n}\n\nFile v1.16.0:references/publishing-clawhub.md\n\n# ClawHub 发布（skill 分发与同步）\n\n> 本文是**维护者手册**——使用者无需阅读。\n> 项目通过 ClawHub 分发：。\n> 以下规则来自实测发布过程，发布任何版本时必须遵守。\n\n## 关键事实\n\n- ❗ **ClawHub 不是 Git 端点** — 仓库远程 `clawhub` 只是发布页地址，\n `git fetch/push clawhub` 必然 404（`repository not found`）。**发布必须走 clawhub CLI**，\n 不能指望 git push。\n- 发布 CLI 由 pnpm 全局安装：`%LOCALAPPDATA%\\pnpm\\clawhub.CMD`\n （PowerShell `PATH` 未包含 pnpm 目录时直接调 `clawhub` 会「无法识别」，需用全路径）。\n- 登录状态用 `clawhub whoami` 验证（应输出 `phoenixlucky`）。\n- 新版本提交后 ClawHub 会跑**安全扫描**（异步、分钟级），**提交成功 ≠ 立即可见**。\n- 发布包内容以**发布时的工作区文件**为准：GitHub 提交 ≠ ClawHub 包同步。\n 打包范围由 `package.json` 的 `files` 字段声明（改目录结构时必须同步核对）。\n\n## 发布陷阱表（C 系，与 F 模式 #1-15 区分）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| C1 | **PowerShell `curl` 是别名** | `curl -s -o NUL https://...` 报「缺少参数 SessionVariable」 | PS 里 `curl` = `Invoke-WebRequest`（参数不兼容）；探测网络/API 一律用 **`curl.exe`** |\n| C2 | **`clawhub publish` 相对路径解析错误** | `publish .` 报 `Error: SKILL.md required` | CLI 默认 `--dir skills`（相对 workdir），相对路径找不到根目录 SKILL.md；✅ 传**绝对路径** |\n| C3 | **发布命令长时零输出** | 前台发布跑 2 分钟无输出被超时终止，ClawHub 无变化 | 上传 registry 需 5-6 分钟且**全程零输出**（易误判卡死）；✅ 用后台运行（`run_in_background`）+ 轮询等待 |\n| C4 | **安全扫描异步** | 发布提交成功（`Update submitted ... pending security scans before it becomes public`）但 registry/页面仍是旧版本号 | 平台规则：扫描通过才公开；✅ 用 `clawhub inspect phoenixlucky/zerotoken-skill --json` 或页面 `og:image` 复查，看到新版本号即已公开 |\n| C5 | **发布前工作区有未提交改动** | 工作区脏时发布，未提交改动**已随包上传 ClawHub** 但 GitHub 缺失，两端分叉 | ✅ 发布前先 `git status` 确认干净（或先提交）再发布；发布后复查 `git status` |\n| C6 | **带 source 参数触发上传 ticket 失效** | `publish ... --source-repo ... --source-commit ` 报 `Skill upload ticket is missing, used, or expired`（连续重试 + 等冷却无效） | 实测：**去掉 `--source-repo` / `--source-commit` 重试即成功**；source 元数据可发布后通过页面/GitHub 关联，不影响打包内容 |\n\n## 推荐发布时序（每次发布固定流程）\n\n```text\n0. git status 确认工作区干净；git log 记录待发布版本号\n1. 一键校验：python scripts/zt.py check\n （回归测试 + 编码审计 + 文档一致性 + 版本号三处联动；与 CI 同一条命令）\n2. git push origin main（GitHub 先行）\n3. clawhub publish <仓库绝对路径> --slug zerotoken-skill --owner phoenixlucky \\\n --version <新版本> --changelog \"<变更摘要>\" --no-input\n —— 先加 --dry-run 预览（应输出 Would publish @），\n 确认无误后移除 --dry-run 再次执行，并放后台运行（陷阱 C3）\n4. clawhub inspect phoenixlucky/zerotoken-skill 复查公开状态（异步，陷阱 C4）\n```\n\n> 版本号用 `python scripts/zt.py version ` 写入三处；`zt.py check` 与 CI 跑同一套校验。\n\nFile v1.16.0:references/refactor-playbook.md\n\n# E 模式参考：重大重构 / 架构调整\n\n> **触发信号**（满足任意一条即可进入此模式）：\n> - 同一模块反复修同一个类型的 bug，修了又犯\n> - 加一个小功能需要改 5+ 个文件，牵一发动全身\n> - 现有架构无法合理支持新需求，强行扩展会导致更深的 technical debt\n> - 测试覆盖率低、或测试需要大量 mock 才能跑，说明耦合度过高\n> - 代码逻辑纠缠不清，修改的「实际影响面」远超「预期影响面」\n>\n> 这是唯一**必须先确认方案再执行**的模式；其他模式识别即执行。\n\n## 流程\n\n1. **诊断根因，不治症状** — 先用跨文件探索工具（`explore`，或宿主提供的代码图工具）了解问题模块的全景（入口、调用链、数据流），定位系统性根源而非表面 bug。\n 产出：根因陈述（1-2 句话）。\n\n2. **评估影响面** — 摸清依赖关系：哪些模块依赖问题代码、哪些测试会受影响、是否有外部调用者。\n 产出：影响模块清单 + 风险等级。\n\n3. **设计方案 & 用户确认** — 输出 2-3 个候选方案的对比（每个含：核心思路、改动量、风险、迁移难度），\n 用 `ask` 让用户选择，**不要替用户做架构决策**。确认后再进入执行阶段。\n\n4. **制定增量迁移计划** — 将重构拆为可独立验证的小步，每步满足：\n - 可回滚（不破坏已有功能）\n - 可通过编译 + 已有测试\n - 新旧代码可共存过渡（strangler fig / feature flag / 适配层）\n 产出：`todo_write` 任务清单（顶层步骤，不含子 bullet）。\n\n5. **安全执行，每步验证** — 按计划逐步执行，每步后：\n - `lsp_diagnostics` 检查编译（宿主提供时）\n - 运行相关测试\n - 更新 `todo_write` 状态\n 发现计划外的依赖时暂停，补评估再继续。不得跳过验证走捷径。\n\n6. **清理收尾** — 删除废弃代码（不留「为了兼容以前」的旧实现，见总纲 #6）、移除过渡兼容层、\n 更新文档 / README / AGENTS.md。最后跑一次完整测试套件。\n\n## 输出模板（重构/架构类）\n\n```text\n问题：<根因 1-2 句>\n方案：<选定的方案简述>\n迁移计划：\n Step 1: <做什么> → 验证：<怎么验证>\n Step 2: ...\n风险：<已知风险和缓解措施>\n状态：进行中 | 已完成\n```\n\n## 关键原则\n\n- **先理解再动手**：E 模式允许较高的 token 消耗用于阅读和理解——诊断和设计方案阶段不做省 token 优化。\n- **不提前优化**：只重构当前确实有问题的部分，不顺手\"优化\"无关代码。\n- **留退出路径**：每一步都可以撤销或暂停，不做不可逆的一次性大改。\n\nFile v1.16.0:references/search.md\n\n# 搜索外部资料规范\n\n> 触发：任务需要外部资料（新闻、人物、公司、社交平台内容、实时信息等）。\n\n## 优先级\n\n| 优先级 | 方式 | 条件 |\n|--------|------|------|\n| 🥇 本地浏览器 MCP 桥 | 通过真实浏览器搜索（搜索引擎不限百度，按效果选） | 本地存在 MCP 桥脚本且服务在线 |\n| 🥈 宿主自带的抓取工具（如 `web_fetch`） | 备选，仅当浏览器桥不可用 | 无条件 |\n\n> **为什么优先真实浏览器？** 纯 HTTP 抓取依赖搜索引擎结果页，曾被反爬返回完全无关内容；\n> 真实浏览器搜索（Playwright/Chrome）结果精准可控。\n\n## 先探测，不要硬编码路径\n\n浏览器桥的调用入口**按实际安装位置探测**，不要假定某个 skill 名或目录存在。探测顺序：\n\n```text\n1. 宿主已注册的浏览器类 MCP 工具（如 mcp-server 提供的 search / navigate）\n2. 仓库或用户目录下已有的 MCP 桥：.reasonix/skills/*/mcp_call.py、mcp-bridge.js\n3. 都没有 → 回退到 web_fetch，或询问用户希望的检索方式\n```\n\n找到入口后，**Windows 上一律通过 Python 包装脚本调用**（`mcp_call.py` 等），\n不要在 PowerShell 里直接调 `node mcp-bridge.js`：\nPowerShell 的引号嵌套与 GBK 编码会破坏 JSON 参数（见 [`windows-powershell.md`](windows-powershell.md) 陷阱 5）。\n\n## 真实浏览器能搜什么\n\n| 场景 | 示例 | 形态 |\n|------|------|------|\n| 🔍 通用搜索 | 搜索新闻、人物、事件 | ` search 关键词` |\n| 🐦 社交媒体动态 | 搜微博、知乎、小红书上的内容 | ` search 微博 关键词` |\n| 🏢 公司/产品信息 | 查询公司背景、产品评测 | ` search 公司名 评价` |\n| 📰 最新资讯 | 今日热点、行业动态 | ` search 今日 热点` |\n\n> **无需为每个平台找专用 MCP server** — 真实浏览器通杀反爬严格的网站；搜索引擎按检索效果自由选择。\n\n**若浏览器桥不可用**：允许使用当前网络可用的其他搜索方式（如 `web_fetch`），\n不要因为首选方案不可用就放弃搜索。\n\n## 什么情况走抓取工具\n\n仅当以下条件**全部满足**时才回退：\n\n1. 浏览器桥入口不存在或 MCP 服务离线\n2. 目标网站没有反爬（非社交平台、非登录墙）\n3. 仅需获取静态页面内容（非 SPA 页面）\n\n## ❌ 禁用行为\n\n- **禁止用抓取工具直抓社交媒体（微博/知乎/小红书等）** — 全部有登录墙/反爬，100% 失败\n- **禁止自己写 Playwright/Puppeteer 脚本** — 已有现成的 MCP 桥，一行搞定\n- **禁止用抓取工具直连搜索引擎（Google/百度/Bing）** — 纯 HTTP 请求会被机器人检测拦截\n\nFile v1.16.0:references/tool-mapping.md\n\n# 工具名映射与宿主专属行为\n\n> 本 skill 描述的是**能力**，不是某个宿主的工具名。\n> 下表把本文档与 `SKILL.md` 中用到的能力映射到具体宿主工具；\n> 只调用当前宿主**实际提供**的等价工具，不要臆造名字。\n\n## 能力 → 工具名\n\n| 能力 | Reasonix | 其他宿主常见名 |\n|---|---|---|\n| 文本搜索（定位行） | `grep` | `search_content` / ripgrep / `grep` |\n| 文件枚举 | `glob` / `ls` | `directory_tree` / `find` / `list_dir` |\n| 局部读取 | `read_file`（`offset` + `limit`） | `read_file` / `open_file` |\n| 写入 / 编辑 | `write_file` / `edit_file` | `apply_patch` / `str_replace_editor` |\n| 同文件多处编辑 | `scripts/batch_edit.py`（宿主若提供 `multi_edit` 可优先用） | `multi_edit` |\n| 待办清单 | `todo_write` | `complete_step` / `update_plan` |\n| 跨文件探索 / 影响面 | `explore`（只读子代理） | `codegraph_context` / `codegraph_trace` / Task |\n| 结构化提问 | `ask` | `ask_user` |\n| 编译 / 类型检查 | `lsp_diagnostics` | `diagnostics` |\n| 网页抓取 | `web_fetch`（宿主提供时） | `fetch` / `browse` |\n\n> 代码图类工具（`codegraph_*`）若宿主提供，在 E 模式下优先于 `explore`——\n> 它给出的是调用链而非搜索命中。没有这类工具时，用 `explore` + `grep` 组合替代。\n\n## 宿主 verification 循环\n\n部分宿主（如带 AutoResearch 签收机制的宿主）会出现：验证证据已提供多次\n（git diff、文件检查、关键词检查），系统仍不接受，`stale_count` 持续累积。\n\n✅ 使用宿主提供的签收工具（如 `complete_step`，`kind: \"verification\"`）推进任务，\n而不是仅靠 `` 之类的文本块。\n✅ 签收证据的 `command` 字段必须与会话历史中的命令文本**完全一致**，否则被视为无效。\n✅ 宿主不提供签收工具时忽略本节——它是宿主行为，不是 Windows / 编码问题。\n\n## plan / todo 注册行为\n\n某些宿主的 plan 模式会把**每层 bullet 列表项**注册为独立待办项，且必须严格线性签收。\n规避方式：\n\n✅ 每个 phase 只写 1 行顶层步骤（共 2-5 个），细节写在说明文字中而非子 bullet。\n\n```text\n✅ 正确：\n1. safe_io.py 新增 safe_append 函数 — 用 open('a', encoding='utf-8') 替代 Add-Content\n\n❌ 错误（会生成 10+ 待办项）：\n1. safe_io.py 新增 safe_append\n - 实现函数\n - 更新文档字符串\n - 导出 __all__\n```\n\n若已陷入子步骤阻塞：优先用宿主的步骤调整机制（如 `complete_step({ step_index: N })`\n跳过中间项）直接签收当前卡住的项。\n\n**签收证据类型规则（宿主提供签收工具时）**\n\n- 工具写入的文件（`write_file` / `edit_file`）→ `files` 证据\n- 脚本写入的文件（如 Python 执行产物）→ `manual` 证据\n- `verification` 证据的 `command` 必须与会话历史中的命令文本完全一致\n- 每次工具调用只签一个步骤，按顺序推进（部分宿主限制：每轮只允许一个成功签收）\n\nFile v1.16.0:references/windows-powershell.md\n\n# F 模式参考：Windows / PowerShell 环境适配\n\n> **触发**：`python scripts/detect_env.py` 报告 `os.name == \"windows\"` 且推荐 shell 为 PowerShell。\n> 自动启用，**无需用户请求**，也不要求任务涉及中文。\n> 系统参数（OS 版本、控制台代码页、中文支持、PowerShell 发行版、Git quotepath）在探测时\n> 存入 `.zerotoken/environment.json`（7 天有效期），后续所有命令选择以保存的参数为准。\n>\n> **不适用**：macOS / Linux → 见 `SKILL.md` 的 G 模式，不要套用本文的规避规则。\n\n## 先决定：用编辑工具还是 Python 脚本\n\n| 情形 | 做法 |\n|---|---|\n| 纯 ASCII 内容、单处改动、文件本身是 UTF-8 | `edit_file` 直接改（B 模式默认路径） |\n| 内容含中文 / emoji / 特殊符号（`+`、反引号、`\\r\\n`） | `write_file` 写 `.py` 脚本，再 `python \"script.py\"` |\n| 同一文件需要多处改动（≥2 处） | 一个 Python 脚本一次完成，或用 `scripts/batch_edit.py` |\n| 批量编码转换 / GBK 污染修复 | `scripts/fix_encoding.py` / `scripts/detect_gbk_contamination.py` |\n| 命令参数本身含中文 | 写 `.py` 脚本执行，**不要**在命令行内联中文 |\n\n判定理由：PowerShell 命令行是编码 + 转义的双重雷区（见陷阱 1 / 8 / 11），\n而 Python 脚本的「写入脚本文件」和「执行脚本」两条路径都受 UTF-8 控制。\n\n## 已知陷阱与解决方案（15 条）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| 1 | **PowerShell 与中文文本冲突** | `bash` 工具传中文给 PowerShell，`+` 被解析为字符串拼接运算符；反引号 `` ` `` 被识别为转义字符；含中文的 PowerShell 字符串报 `Missing ')'` 语法错误 | ❌ 不要直接在 `bash` 命令中嵌入含 `+` 的中文
✅ 改为 `write_file` 写 `.py` 脚本文件，再用 `python \"script.py\"` 执行 |\n| 2 | **文件编码不一致** | 部分文件（如旧中文 Markdown）实际是 UTF-16 编码；Python 默认 UTF-8 读取抛 `UnicodeDecodeError`；旧文件中已有因编码损坏产生的替换字符（U+FFFD），导致字符串精确匹配失败 | ✅ 统一采用 UTF-8 编码读写
✅ 安全读取方案见下文的「安全文件读写模板」 |\n| 3 | **edit_file 同文件连续编辑阻塞**（宿主行为，与系统无关） | 同一文件的多处修改，第一次 `edit_file` 后第二次被拒，错误：`fresh read required — was already modified earlier this turn` | ✅ 对同一文件的多处修改，一次性用 Python 脚本完成
✅ 或用宿主提供的多编辑工具一次传入多个替换（≤5 个以内）
✅ 维护一个更新脚本，执行后统一验证 |\n| 4 | **Git 中文文件名转义显示** | `git diff --stat` 显示 `\\xxx\\xxx` 编码序列，无法直接阅读中文文件名 | ✅ 先执行 `git config core.quotepath false` |\n| 5 | **PowerShell → Node.js 中文 JSON 参数断裂** | 调用 `node mcp-bridge.js call tools/call '{\"name\":\"x\",\"arguments\":{\"url\":\"中文\"}}'` 时，中文导致 JSON 解析失败 | ✅ **不要直接调 `node mcp-bridge.js`**
✅ 改用 Python 包装脚本（本地 MCP 桥自带 `mcp_call.py`），其内部已用 `json.dumps()` 正确序列化 |\n| 6 | **宿主 verification 死循环**（宿主行为，与系统无关） | 验证证据已提供多次（git diff、文件检查、关键词检查），但系统始终不接受；`stale_count` 持续累积 | ✅ 见 [`tool-mapping.md`](tool-mapping.md) 的「宿主 verification 循环」 |\n| 7 | **Python 控制台输出中文失败** | Python 的 `print()` 在 PowerShell 控制台下因 GBK 编码报错：`UnicodeEncodeError: 'gbk' codec can't encode character` | ✅ 不直接 `print()`，写入 `.txt` 文件后用 `read_file` 查看
✅ 使用 `with open(out_path, 'w', encoding='utf-8') as f: f.write(result)` |\n| 8 | **PowerShell 中 `\\r\\n` 转义** | PowerShell 脚本中 `` `r`n `` 的反引号被解释为换行转义符，导致语法错误 | ✅ 不在 PowerShell 中拼接含换行的多语言文本
✅ 改用 Python 的 `\\n` 处理换行 |\n| 9 | **PowerShell Add-Content 使用 GBK 编码污染 UTF-8 文件** | 用 `Add-Content` 向 UTF-8 文件追加中文后，新内容变为乱码（GBK 字节被误读为 UTF-8，出现 U+FFFD 替换字符），文件末尾出现 `0x81` 等无效 UTF-8 字节
根因：PowerShell 的 `Add-Content` 默认使用系统区域编码（Windows 中文版为 GBK）写入 | ❌ **禁止直接使用 PowerShell Add-Content 追加含中文的内容**
✅ 使用 Python 安全追加：`open('file.md', 'a', encoding='utf-8').write('内容')`
✅ 或用 `safe_io.py` 的 `safe_append()` 函数
✅ 已污染的文件用 `detect_gbk_contamination.py` 检测修复 |\n| 10 | **PowerShell `&&` 链式操作不兼容** | PowerShell 不支持 bash 风格的 `&&` 运算符，`cmd1 && cmd2` 报语法错误 | ✅ 用 `;` 无条件链式
✅ 用 `if ($?) { ... }` 做条件链式 |\n| 11 | **内联 `python -c` 中文 SyntaxError** | `python -c \"含中文的代码\"` 在 PowerShell 下因编码问题导致 SyntaxError | ❌ 不要用 `python -c` 传入含中文的代码
✅ 改为 `write_file` 写 `.py` 脚本执行 |\n| 12 | **终端显示层中文乱码（文件内容正确）** | PowerShell 终端显示中文为乱码/问号，但文件内容实际正确（GBK 终端显示 UTF-8 编码文件） | ✅ 用文件大小/行数验证
✅ 用 `chcp 65001` 切换终端到 UTF-8 |\n| 13 | **PowerShell 读取附件时中文乱码显示** | 用 `Get-Content` / `type` 读取附件（用户上传的 .md/.txt/.csv 等）时中文显示为乱码（如 `鐗堟湰鍙?1.9.1`），但用 `read_file` 或编辑器打开内容正常
根因：Windows PowerShell 5.1 的 `Get-Content` 默认按 ANSI 代码页（中文系统为 GBK/936）解码无 BOM 的 UTF-8 文件，属**显示层**问题，文件本身未损坏
⚠️ 若把\"显示乱码\"误判为\"文件被污染\"并盲目转码重写，反而会造成真正的污染 | ✅ **优先用 `read_file` 工具读取附件**（按 UTF-8 解码，显示正确）
✅ 必须在 PowerShell 中读时显式指定编码：`Get-Content -Encoding UTF8 附件.md`（PS 7+ 默认 UTF-8；5.1 必须加 `-Encoding UTF8`）
✅ 附件本身是 GBK/UTF-16 等非 UTF-8 编码时，用 `safe_io.read_text()` 自动检测（UTF-8 BOM / UTF-16 BOM / GB18030）
✅ 先确认附件真实编码再处理；显示乱码≠文件损坏，禁止据此盲目转码 |\n| 14 | **PowerShell 写入命令默认编码不统一（写方向污染）** | PS 5.1 下 `Set-Content` / `Add-Content` 默认按 GBK 写出：纯汉字变成 GBK 字节（追加进 UTF-8 文件即污染），emoji 等字符**静默写成 `?` 丢字**；`Out-File` / `>` 重定向默认 UTF-16 LE（带 BOM）；`-Encoding UTF8` 写出的又是 UTF-8 **带 BOM**（部分工具解析异常）
已实测：同一 emoji 字符串经 `Set-Content` 默认写出为字节 `3F`（问号） | ✅ PowerShell 中写 UTF-8 文本统一用 .NET API：`[IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`（无 BOM；Append 用 `WriteAllText(..., $text, $enc)` 前先读原内容，或直接用 Python）
✅ 跨脚本/含中文的写入一律走 Python：`safe_io.safe_write()` / `safe_append()`（UTF-8 无 BOM + LF）
✅ 万不得已必须用 `Set-Content -Encoding UTF8` 时，知晓会带 BOM；禁止用其默认编码写任何非 ASCII 内容 |\n| 15 | **`Add-Content -Encoding UTF8` 追加不补换行导致粘连 + 带 BOM** | 即使显式指定 `-Encoding UTF8`，`Add-Content` 追加到不以换行结尾的文件时**不自动补换行**，两段内容直接粘连成一行（实测：`base` + 追加 → `base## 标题 ...`）；且写出的内容带 UTF-8 BOM | ✅ 追加操作改用 `safe_io.safe_append()`：自动补换行、UTF-8 无 BOM
✅ 纯 PowerShell 方案需自行判断末尾换行再拼接，复杂且易错，不建议
✅ 追加后发现首段粘连，检查是否由本陷阱导致，不要误判为内容错误 |\n\n## 脚本工具（`scripts/` 目录）\n\n**统一入口（推荐）：** `python scripts/zt.py <命令>` —— `zt.py help` 列出全部命令，\n`zt.py check` 一键跑完全部校验（回归测试 / 编码审计 / 文档一致性 / 版本联动）；\n参数原样透传，命令示例见 `zt.py help`。下表脚本均可独立调用（zt.py 只是转发）。\n\n仓库自带一系列 Python 脚本，开箱即用，覆盖 F 模式的常见操作：\n\n| 脚本 | 解决问题 | 用法示例 |\n|------|----------|----------|\n| `detect_env.py` | 环境识别：探测 OS / Shell / 控制台编码 / 中文支持 / PowerShell 版本并保存系统参数 | `python scripts/detect_env.py --force`（结果存 `.zerotoken/environment.json`，7 天有效期） |\n| `safe_io.py` | #2 编码不一致（UTF-8 BOM / UTF-16/32 BOM / GB18030） / #7 无法 print 中文 / #9 安全追加替代 Add-Content（自动补换行） / #13 附件乱码读取（自动检测编码） / #14 写方向编码统一（safe_write 无 BOM + LF） | `from safe_io import read_text, safe_write, safe_append, write_result`（编码无法确定时显式抛 `UnknownEncodingError`，不静默替换） |\n| `detect_gbk_contamination.py` | #9 检测修复 GBK 编码污染 | `python scripts/detect_gbk_contamination.py scan .` / `python scripts/detect_gbk_contamination.py fix . --backup` |\n| `batch_edit.py` | #3 edit_file 连续编辑阻塞 | `python scripts/batch_edit.py file.json replacements.json` |\n| `fix_encoding.py` | #2 批量编码转换 | `python scripts/fix_encoding.py scan .` / `python scripts/fix_encoding.py convert . --backup` |\n| `verify_output.py` | #7 控制台输出 / 验证结果落文件 | `python scripts/verify_output.py \"检查项\" out.txt --pass \"✓ 通过\"` |\n| `init_env.ps1` | #4 Git 配置 / 环境初始化 | 在新会话中 `. ./scripts/init_env.ps1` |\n\n## 推荐工作流\n\n当 `detect_env.py` 识别到 Windows 系统时，按以下步骤替代默认工作流：\n\n```text\n0. （首次）python scripts/detect_env.py 探测系统参数并保存\n （.zerotoken/environment.json，7 天有效；之后每次会话自动复用）\n1. 判断改动类型（见上文「先决定：用编辑工具还是 Python 脚本」）\n2. 需要脚本时：write_file 写 Python 更新脚本（.py）\n3. python \"script.py\" 执行（避免 PowerShell + edit_file 的所有问题）\n4. git diff --stat 验证文件变更\n5. 用 verify_output.py 输出验证结果到 .txt 文件\n6. read_file 读取验证结果\n7. 签收/收尾（宿主若提供 complete_step 等签收工具，见 references/tool-mapping.md）\n```\n\n## 安全文件读写模板\n\n优先直接调用 `safe_io`（`read_text` / `safe_write` / `safe_append`）；\n需要内联时使用等价写法：\n\n```python\n# 安全读取（UTF-8 / UTF-8 BOM / UTF-16 / GB18030 自动检测）\nwith open(path, 'rb') as f:\n raw = f.read()\n\nfrom safe_io import decode_bytes # 无法确定编码时显式抛错\ncontent = decode_bytes(raw, path)\n\n# 安全写入（统一 UTF-8，行尾 LF；newline='\\n' 防止 Windows 文本模式写成 CRLF）\nwith open(path, 'w', encoding='utf-8', newline='\\n') as f:\n f.write(content)\n\n# 安全追加（替代 Add-Content，避免 GBK 污染；newline='\\n' 同上）\nwith open(path, 'a', encoding='utf-8', newline='\\n') as f:\n f.write(content)\n if not content.endswith('\\n'):\n f.write('\\n')\n```\n\n## 不做什么\n\n❌ 不在 `bash` 命令中嵌入含特殊符号（`+`、`` ` ``）的中文字符串\n❌ 不连续对同一文件进行多次 `edit_file` 调用\n❌ 不直接在 PowerShell 中用 `print()` 输出中文\n❌ 不忽略 `git config core.quotepath` 设置\n❌ **不使用 PowerShell 的 `Add-Content` 追加含中文的内容** — 改用 Python `open(path, 'a', encoding='utf-8')` 或 `safe_io.safe_append()`\n❌ **不在 PowerShell 中直接调用 `node mcp-bridge.js` 传递中文 JSON 参数** — 改用 Python 包装脚本\n❌ **不用 `web_fetch` 直抓社交媒体（微博/知乎/小红书等）** — 100% 被登录墙或反爬拦截\n❌ **不自己写 Playwright/Puppeteer 脚本**（已有现成 MCP 桥，见 [`search.md`](search.md)）\n❌ **不使用 `python -c` 内联含中文的代码** — 改用 `write_file` + `python \"script.py\"` 两步法\n❌ **不使用 `&&` 链式命令** — PowerShell 不支持，改用 `;` 或 `if ($?) { ... }`\n❌ **不依赖终端输出验证中文内容** — 用文件内容验证替代\n❌ **不用 `Get-Content` 直接查看含中文的附件** — 5.1 默认按 GBK 解码会显示乱码，改用 `read_file` 工具或 `Get-Content -Encoding UTF8`；显示乱码≠文件损坏，禁止据此盲目转码\n❌ **不在 PS 5.1 中用 `Set-Content` / `Add-Content` / `Out-File` 的默认编码写任何非 ASCII 内容** — 默认 GBK 会污染 UTF-8 文件、emoji 静默变 `?`；写方向统一走 Python `safe_io.safe_write()` / `safe_append()`，或 .NET `[IO.File]::WriteAllText($path, $text, [Text.UTF8Encoding]::new($false))`\n❌ **不依赖 `Add-Content -Encoding UTF8` 做追加** — 仍会带 BOM 且目标不以换行结尾时不补换行导致内容粘连；统一用 `safe_io.safe_append()`\n\nFile v1.16.0:AGENTS.md\n\n# Project memory\n\n## 项目结构\n\n- `SKILL.md` — **常驻核心**（快速决策表 / 核心原则 / 输出格式 / 质量底线）。\n 体积预算 ≤14KB，超出即说明细节该外移到 `references/`。\n- `references/` — **按需读取**的细节：`windows-powershell.md`（F 模式 15 条陷阱）、\n `refactor-playbook.md`（E 模式）、`search.md`、`tool-mapping.md`、`publishing-clawhub.md`。\n- `scripts/` — 编码与一致性工具；`safe_io.py` 是其余脚本的公共依赖（`ensure_utf8_stdio` / `safe_print`）。\n- `docs/unicode-encoding-spec.md` — 编码规范的本仓库执行细则。\n- 分发：GitHub + ClawHub 双端；打包范围由 `package.json` 的 `files` 字段声明。\n\n## 校验命令（改完必跑，与 `.github/workflows/ci.yml` 一致）\n\n```powershell\npython scripts/zt.py check # 一键：回归测试 + 编码审计 + 文档一致性 + 版本联动\n```\n\n排查时单步跑（入口一览见 `python scripts/zt.py help`）：\n\n```powershell\npython scripts/zt.py env # 识别系统参数（写 .zerotoken/environment.json）\npython scripts/zt.py audit # 文档一致性：体积/链接/计数/脚本引用/异体字\npython scripts/zt.py encoding # 编码合规：UTF-8/替换字符/混合换行\npython scripts/zt.py version # 版本号三处联动（带版本号=写入）\n```\n\n> `check / audit / encoding / version` 支持 `--json [--out 文件]`（供 AI / CI 解析）；\n> `env / gbk / convert / edit / verify` 目前为文本输出。`scripts/` 下的原脚本仍可独立调用。\n\n## 发布（仅维护者）\n\n- 版本号一律用 `python scripts/zt.py version ` 写入三处，不要手改单点。\n- 发布时序、C1-C6 陷阱与 ClawHub CLI 用法见 `references/publishing-clawhub.md`；\n **ClawHub 不是 Git 端点**，`git push` 发不出去。\n\n## Notes\n\n- 方式二：从远程 Skill 仓库引用（推荐，始终获取最新版本） 安装这个技能 https://clawhub.ai/phoenixlucky/zerotoken-skill\n\n## 编码规范（必须遵守）\n\n- 生成/修改任何代码、配置、文档前，先读 `docs/unicode-encoding-spec.md`（Unicode 安全编码规范 15 条 + 项目执行细则）。\n- 硬性要求：文本文件统一 UTF-8（`.ps1` 例外必须 UTF-8 with BOM）；`open()` 一律显式 `encoding='utf-8'`；禁止 `errors='replace'` 静默损坏数据；Python 控制台输出优先 `sys.stdout.reconfigure(encoding='utf-8')`（本仓库统一走 `safe_io.safe_print`）；HTTP 头显式 `charset=utf-8`；JSON 用 `ensure_ascii=False`。\n- 完成后运行 `python scripts/audit_encoding.py --root . --out audit_result.txt` 检查（无 non-utf8、无替换字符、无混合换行）。\n\nFile v1.16.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## [1.16.0] - 2026-09-20\n\n### Added\n- `scripts/audit_skill.py` 新增第 10/11 项检查：站内 Markdown 锚点有效性\n （近似 github-slugger 规则还原锚点，兼容 emoji 标题）、每个非测试脚本\n 必须在文档中被引用（`scripts/test_*.py` 豁免，防新增脚本漏改清单）。\n- `scripts/test_zt.py` 回归测试（测试自动发现、路由退出码、help 输出）。\n- `package.json` 补 `repository` / `homepage` / `bugs` 元数据。\n\n### Fixed\n- README 指向 `SKILL.md` 的 4 个锚点失效：片段带了 emoji，而 GitHub 生成锚点时会\n 剥离 emoji（`#⚔️-ai-…` 实际应为 `#-ai-…`）；现由 audit_skill 锚点检查长期兜住。\n\n### Changed\n- README 深度瘦身（19304 B -> 10632 B，-45%）：新增目录；合并重复的安装方式；\n 把「场景详解 A-G」「尉缭子十原则全文」「搜索 / 编码 / 提示词 / 强化模式」等\n `SKILL.md` / `references/` 的副本改为摘要 + 入口（消除双份事实源）；\n 平台小节由 6 张卡片改为一张表；新增 CI 状态徽章；\n 修正「五种主流 Agent 工具」与 6 个小节的口径。\n- `assets/zerotoken-banner.webp` 重压为 720x1080 / q72：582 KB -> 165 KB（-72%）。\n\n## [1.15.0] - 2026-09-20\n\n### Added\n- `scripts/audit_skill.py` 新增第 9 项检查：CHANGELOG.md 顶部版本必须等于\n `package.json` 版本（版本号隐性第 4 处锚点，此前无机器校验）。\n- 回归测试 `scripts/test_audit_skill.py` / `scripts/test_audit_encoding.py`\n （合规 fixture 通过 + 注入缺陷命中），回归测试 3 -> 5 个。\n- `.editorconfig`：charset / eol / final-newline 的编辑器侧约束，与 `.gitattributes`\n 及编码规范一致；`.ps1` 标注 `utf-8-bom`。\n- `package.json` 增 `scripts.check`（等价 `python scripts/zt.py check`）。\n\n### Fixed\n- `scripts/audit_encoding.py` 纳入 BOM 规则校验：`.ps1` 必须 UTF-8 with BOM，\n 其余文本必须无 BOM（此前只统计不判违规）。\n- `scripts/audit_encoding.py` 改走 `safe_io`（`ensure_utf8_stdio` / `safe_print` /\n `safe_write`），消除「工具不守自身编码规范」的漂移。\n\n### Changed\n- `SKILL.md` 常驻体积预算 12KB -> 14KB（`audit_skill.py` 的 `SKILL_SIZE_BUDGET`），\n 并同步 `AGENTS.md` / `README.md` 口径；实占 12194 B，此前仅余 94 B。\n- `AGENTS.md` 修正「所有命令支持 `--json`」的表述：实际仅\n `check / audit / encoding / version` 支持，其余命令为文本输出。\n- `scripts/zt.py` 的 `check` 步骤改为自动发现 `scripts/test_*.py`，新增测试无需手改入口。\n\n## [1.14.0] - 2026-09-15\n\n### Added\n- `scripts/bump_version.py` — 版本号三处联动的校验与写入（`package.json` /\n SKILL.md frontmatter / README badge）。`--check` 供 CI 与发布前使用，\n 终结 v1.13.2 记录的「三处联动只能人工核对」漏改问题。\n- `scripts/audit_skill.py` — 文档一致性审计（8 项）：版本三处一致、SKILL.md 体积预算、\n Markdown 相对链接存在性、核心原则条数（SKILL.md vs README）、`scripts/*.py` 引用存在性、\n F 模式陷阱条数与文案声明一致、核心文档不得出现宿主专属工具名、\n 非规范 CJK 字符（康熙部首 / 兼容表意文字）。\n- `.github/workflows/ci.yml` — 最小 CI：两个回归测试 + 编码审计 + 文档一致性 + 版本联动。\n- `AGENTS.md` 补项目结构、校验命令、发布指针（原先只有编码规范与一条安装笔记）。\n\n### Fixed\n- SKILL.md 中的异体字：用 Kangxi 部首 U+2F0C 冒充「文」，视觉相同但码位不同，\n 搜索与精确匹配会静默失败。同类问题现由 `audit_skill.py` 长期兜住。\n- README 核心原则表长期只有 7 条：v1.12.0 新增的 #8「先识别环境，再选 Shell」未同步，\n 现由 `audit_skill.py` 强制两边条数一致。\n- **`bump_version.py` 写入路径崩溃**：`apply_version()` 依赖正则的第 3 组拼接文本，\n 而 SKILL.md 的锚点只有 2 组 → `python scripts/bump_version.py <版本号>` 抛\n `IndexError: no such group`，且此时 `package.json` 已被改写、另外两处未改（半写入状态）。\n 改为基于第 2 组的 `match.span()` 替换，对组数变化免疫；补 `test_bump_version.py` 兜住。\n （该路径自引入起只被 `--check` 覆盖过，写入分支从未被测 —— 教训：CLI 的写入分支必须有测试。）\n- `audit_encoding.py` / `bump_version.py` 统一返回退出码：发现问题返回 1\n （此前 `audit_encoding.py` 恒返回 0，CI 会把编码违规当成功放行）。\n\n### Changed\n- 文档统一以 zt.py 为主入口：`README.md`（F 模式段 + 文档地图）、\n `references/windows-powershell.md`（脚本工具段）、`AGENTS.md`（校验命令）、\n `references/publishing-clawhub.md`（发布时序 7 步 → 4 步，校验收敛为一条 `zt.py check`）、\n `.github/workflows/ci.yml`（5 个 step → 1 个）。\n- `bump_version.py` 的 `check()` 重构为 `gather()`（返回结构化结果，CLI 与 JSON 共用）。\n- `audit_encoding.py` 的 `--out` 默认值改为 `None`（默认行为仍是写 `audit_result.txt`；\n JSON 模式不落盘，除非显式 `--out`），避免 CI / `zt.py check` 污染工作区。\n- `SKILL.md` description 补中文触发词（「省 token / 简洁点 / 直接给结果 / 少废话 / 别解释」），\n 提高宿主自动加载命中率；新增一行工具入口指引（体积仍在 12KB 预算内）。\n\n### Tests\n- 新增负向探针验证：对仓库副本注入 8 类缺陷（版本漂移、坏链接、缺脚本引用、\n 原则条数不一致、陷阱条数漂移、宿主专属工具名、异体字），`audit_skill.py` 全部命中。\n\n## [1.13.2] - 2026-08-28\n\n### Fixed\n- **README 顶部版本徽章漏更新**：停在 `version-1.11.0`（v1.12.0 起 bump 只改\n `package.json` + `SKILL.md` frontmatter，README badge 未同步）。\n 已更新为 `version-1.13.2`。\n- 教训固化：**版本号 bump 是三处联动**（`package.json` / `SKILL.md` frontmatter /\n `README.md` 顶部 shield badge），发布节奏中应统一核对。\n\n## [1.13.1] - 2026-08-28\n\n### Changed\n- **README.md 平台集成指南更新**（补发到 ClawHub 发布包）：\n - 方式一标注「（推荐，AI助手安装）」\n - 方式二、方式三补充 GitHub 源安装命令\n （`install-source --source https://github.com/phoenixlucky/zerotoken-skill` /\n 「安装这个技能 https://github.com/phoenixlucky/zerotoken-skill」），\n 与 ClawHub 源并列\n- 教训固化：**发布包内的 README 以发布时工作区文件为准**——GitHub 提交 ≠\n ClawHub 包同步，README 等文档后续改动需新发版本（docs-only 可 bump patch）\n\n## [1.13.0] - 2026-08-28\n\n### Added\n- **ClawHub 发布规范**（source: v1.12.0 实测发布过程）：\n - SKILL.md 新增「📤 ClawHub 发布」章节：关键事实 + 发布陷阱表（C1-C5）+\n 固定发布时序\n - **C1**：PowerShell `curl` 是 `Invoke-WebRequest` 别名（参数不兼容），网络探测一律用 `curl.exe`\n - **C2**：`clawhub publish` 相对路径解析错误（默认 `--dir skills` 找不到根目录 SKILL.md），\n 必须传绝对路径，且先 `--dry-run` 预览\n - **C3**：发布命令上传 registry 需 5-6 分钟且全程零输出，前台运行会被超时终止，\n 必须后台运行 + 轮询等待\n - **C4**：ClawHub 安全扫描异步——提交成功（`pending security scans`）≠ 公开，\n registry 仍是旧版本号，用 `clawhub inspect` 复查\n - **C5**：发布前工作区必须干净（未提交改动会随包上传 ClawHub 但 GitHub 缺失，\n 两端分叉），发布前后各查一次 `git status`\n - 关键事实澄清：ClawHub 不是 Git 端点（`git fetch/push clawhub` 404），\n 发布必须走 clawhub CLI（pnpm 全局安装于 `%LOCALAPPDATA%\\pnpm\\clawhub.CMD`，用全路径调用）\n- README.md「📖 核心文档」索引新增 ClawHub 发布条目\n\n## [1.12.0] - 2026-08-25\n\n### Added\n- **环境识别与系统参数持久化**：新增 `scripts/detect_env.py` — 任何涉及命令行执行的\n 任务开始时先探测当前系统参数并保存到 `.zerotoken/environment.json`（7 天有效期）：\n OS 名称/版本、推荐 Shell（Windows→PowerShell，Linux→bash，macOS→zsh）、\n 控制台编码（stdout encoding + Windows ANSI/OEM 代码页）、\n **中文字符支持判定**（`console.cjk_capable`）、PowerShell 可用性/版本/发行版\n （5.1 Desktop 与 7+ Core 编码行为不同）、Git `core.quotepath` 现状\n- 新增 G 模式（POSIX 标准工作流）：detect_env.py 识别到 Linux/macOS 时自动启用，\n 使用 sh/bash/zsh 工具链，明确不套用 F 模式的 PowerShell 规避规则\n- 核心原则新增 #8「先识别环境，再选 Shell」：命令行任务第一步先获取并保存系统参数，\n 之后所有命令按已保存参数选择 Shell——**Windows 一律 PowerShell，禁用 bash**\n- `init_env.ps1` 新增 [0.5] 系统参数识别段：输出 PowerShell 版本/发行版、ANSI 代码页、\n 中文字符支持判定，并联动 `detect_env.py` 输出完整探测报告\n- `docs/unicode-encoding-spec.md` 新增「Shell 选择规则」章节：先探测系统参数再选 Shell，\n 中文支持能力以 `console.cjk_capable` 为准\n- 回归测试 `scripts/test_detect_env.py`：recommended_shell 分支、CJK 判定矩阵、\n 结构完整性、持久化 round-trip / 过期拒绝 / 损坏拒绝\n\n### Changed\n- **F 模式触发条件放宽**：由「Windows/PowerShell + 中文文本且用户确认」改为\n 「detect_env.py 识别到 Windows 系统即自动启用」，中文支持内置于环境识别结果，\n 不再要求任务涉及中文\n- SKILL.md / README.md：F 模式描述同步改写为自动识别；模式计数更新为七种（A-G）；\n 清除全部 ```` ```bash ```` 代码块标记（Windows 环境下不再展示 bash 用法）\n- 工具清单补齐：SKILL.md 脚本表与 README.md 工具集列表均加入 `detect_env.py`\n\n### Fixed\n- `detect_env.py` 时间戳格式与过期解析不一致的 bug（`detected_at` 统一为\n 紧凑格式供 `is_fresh()` 解析，另附人类可读的 `detected_at_iso`）\n- `init_env.ps1` 变量 `$psEdition` 与 PS 只读自动变量 `$PSEdition` 冲突\n （PS 变量名大小写不敏感），更名为 `$psEditionName`\n\n## [1.11.0] - 2026-08-14\n\n### Added\n- 新增陷阱 #14：PS 5.1 写方向编码不统一 — `Set-Content`/`Add-Content` 默认按 GBK\n 写出（纯汉字→GBK 字节污染 UTF-8 文件；emoji 等字符**静默写成 `?` 丢字**，\n 字节级实测为 `3F`），`Out-File` / `>` 默认 UTF-16 LE，显式 `-Encoding UTF8`\n 又带 BOM。修复方案：PowerShell 内写 UTF-8 统一用\n `[IO.File]::WriteAllText($path, $text, [Text.UTF8Encoding]::new($false))`；\n 含中文/emoji 的写入一律走 Python `safe_io.safe_write()` / `safe_append()`\n- 新增陷阱 #15：`Add-Content -Encoding UTF8` 追加到不以换行结尾的文件时**不补换行**\n 导致内容粘连（实测 `base` + 追加标题 → 粘连成一行），且带 BOM。\n 修复方案：统一改用 `safe_io.safe_append()`（自动补换行、UTF-8 无 BOM）\n- `docs/unicode-encoding-spec.md` 新增「文件写入编码矩阵（PS 5.1 实测）」：\n Set-Content / Add-Content / Out-File / WriteAllText 四种方式的默认与显式行为对照\n- `scripts/init_env.ps1` 新增第 0 步：把当前会话 `[Console]::OutputEncoding` /\n `$OutputEncoding` 切到 UTF-8（仅当前会话生效，不改系统全局设置），\n 缓解终端显示层中文乱码\n\n### Changed\n- `scripts/safe_io.py` 重构：新增 `sniff_encoding()`（BOM→UTF-8→GB18030 单一检测核心）\n 与 `decode_bytes()`；编码无法确定时显式抛 `UnknownEncodingError`，\n **移除 `errors='replace'` 静默损坏兜底**（对齐 docs 规范「禁止静默替换」；\n `strict=False` 仅限查看场景且禁止回写）。`safe_read` 保留为兼容别名，\n UTF-16/32 解码统一交由对应 codec 剥离 BOM（避免开头残留 U+FEFF）\n- `scripts/safe_io.py` `safe_append()` 修复段间粘连：目标文件存在且不以换行结尾时\n 先补换行再追加，对齐 Add-Content「每次追加自带换行」语义\n- 五个脚本的重复 `_ensure_utf8_stdio` + `sp` 副本统一收敛到\n `safe_io.ensure_utf8_stdio` / `safe_print`（batch_edit / verify_output /\n fix_encoding / detect_gbk_contamination 仅 import 复用）；\n `batch_edit.py` 删除行为分裂的本地 `safe_read`，改用统一的 `read_text`\n- 同步更新 `SKILL.md`（陷阱表 13→15 条、模式速查、不做什么、工具表）、\n `README.md`（计数引用与 F 模式描述）\n\n### Tests\n- `scripts/test_safe_io.py` 扩充为完整回归：sniff 全分支、BOM 剥离无 U+FEFF、\n unknown 抛错、strict/非 strict、safe_write/safe_append 无 BOM+LF+补换行、\n write_result 往返\n\n## [1.10.1] - 2026-08-13\n\n### Changed\n- 版本号 1.10.0 → 1.10.1\n\n### Added\n- 新增陷阱 #13：PowerShell 读取附件时中文乱码显示（Get-Content 默认按 ANSI/GBK 解码\n UTF-8 无 BOM 文件），属显示层问题、文件未损坏。修复方案：优先用 `read_file` 工具\n 读取附件；必须在 PowerShell 中读时显式 `Get-Content -Encoding UTF8`；非 UTF-8 附件\n 用 `safe_io.safe_read()` 自动检测编码；禁止把显示乱码误判为文件污染而盲目转码\n- 同步更新 `SKILL.md`（陷阱表、模式速查表、不做什么）、`README.md`（3 处引用）、\n `docs/unicode-encoding-spec.md`（读取附件/文件编码细则）\n\n## [1.10.0] - 2026-08-10\n\n### Changed\n- 版本号 1.9.1 → 1.10.0\n- 文档排版与结构规范化：修复 `SKILL.md` 未闭合代码块（「精准提示词模板」标题此前被吞进代码块）；`SKILL.md` 顶层章节标题统一 emoji 前缀（与 README 一致）；`README.md` 与 `SKILL.md` 重复的 5 个章节（尉缭子十原则、搜索资料规范、精准提示词模板、ZeroToken 强化模式、退出条件）精简为摘要 + 锚点链接，单一信息源；修复 `docs/unicode-encoding-spec.md` 死链引用\n- 搜索资料规范放宽：Chrome MCP 搜索引擎**不限百度**（百度只是默认，网络可用时 Bing / Google / 知乎等按检索效果自由选择）；Chrome MCP 不可用时允许使用当前网络可用的其他搜索方式（含 `web_fetch`），不再因首选方案不可用而放弃搜索。同步更新 `README.md`、`SKILL.md`\n- 落地「Unicode 安全编码规范」（新增 `docs/unicode-encoding-spec.md`，15 条硬性规定 + 项目执行细则；AGENTS.md 增加编码规范约束）\n- 所有 Python 脚本：控制台输出优先 `sys.stdout.reconfigure(encoding='utf-8')`（Python 3.7+），不再把中文替换成 `?`；写模式 `open()` 显式 `newline='\\n'`，避免 Windows 文本模式把 LF 写成 CRLF\n- `scripts/batch_edit.py` / `scripts/verify_output.py`：去除 `errors='replace'` 静默损坏，非 UTF-8/UTF-16/GB18030 文件显式抛错提示先检查原编码\n- `scripts/init_env.ps1` 转为 UTF-8 with BOM（Windows PowerShell 5.1 解析中文必需）；清理未使用变量\n- `.reasonix/skills/mcp-streamable-connect/mcp-bridge.js`：HTTP `Content-Type` 显式声明 `charset=utf-8`\n- SKILL.md「安全文件读写模板」更新（写/追加显式 `newline='\\n'`），替换字符示例改为文字描述（U+FFFD）\n\n### Added\n- 新增 `scripts/audit_encoding.py` 全项目编码审计工具（UTF-8 / BOM / 替换字符 / 混合换行检测）\n\n## [1.9.1] - 2026-08-08\n\n### Changed\n- 版本号 1.9.0 → 1.9.1\n\n## [1.9.0] - 2026-08-07\n\n### Added\n- SKILL.md 核心原则之后新增「AI 编程总纲（尉缭子十原则）」章节 — 以《尉缭子》兵法治编程纪律：先谋后动、统一方案、职责明确、不得越权、唯一命令、禁止旧令、严格执行、最小改动、可追溯、验证先于结束\n- 十原则以「原则 + 要求 + 违反示例」表格精炼呈现，并给出与 B/C/E 任务模式的对应关系及可直接用作 System Prompt 的总纲引文\n- 核心理念：省 token 是效率（ZeroToken），尉缭子是秩序（权限边界、单一指令、责任明确、执行一致）\n\n## [1.8.2] - 2026-07-24\n\n### Added\n- 新增陷阱 #10-#12：PowerShell `&&` 不兼容、内联 `python -c` SyntaxError、终端显示层中文乱码\n- 核心原则第3条补充大文件分页读取规则\n- 核心原则第6条补充 `complete_step` 证据类型规则（files/manual/verification 用法 + 单步签收）\n- 「不做什么」新增 3 条禁用规则\n\n## [1.8.1] - 2026-07-24\n\n### Added\n- 增强搜索规范：新增「Chrome MCP 能搜什么」场景表，消除 AI 不知道 Chrome MCP 能搜微博/新闻等的问题\n- 新增「禁用行为」三项硬约束：禁 web_fetch 直抓社交平台、禁自写 playwright 脚本、禁 web_fetch 直连搜索引擎\n\n## [1.8.0] - 2026-07-?? (unreleased)\n\n### Added\n- 适配 browser-localmcp-skills：新增 mcp_call.py Python 包装脚本，彻底规避 Windows PowerShell 引号嵌套和 GBK 编码崩溃问题\n- SKILL.md 新增「搜索资料指南」章节，明确 Chrome MCP 优先搜索策略\n- SKILL.md 全量示例迁移至 mcp_call.py，消除 Windows 平台调用屏障\n\n### Fixed\n- 规避「Bing 搜索返回无关结果」问题，强制优先走 Chrome MCP（百度搜索）\n\n## [1.7.2] - 2026-07-22\n\n### Fixed\n- 重新发布 v1.7.2 以修复 ClawHub 版本列表未更新的问题（前版 publish 成功但未写入数据库）\n- 内容与 v1.7.0 一致\n\n## [1.7.1] - 2026-07-22\n\n### Fixed\n- 重新发布以刷新 ClawHub 页面展示版本（技术性 bump，内容与 v1.7.0 一致）\n\n## [1.7.0] - 2026-07-21\n\n### Security\n- **Tp4 (MCP Tool Poisoning)** — 重写 SKILL.md `description` frontmatter，从纯\"token-efficient discipline\"扩展为同时声明文件系统工具能力的透明描述。\n- **Language Policy Opt-in** — 添加 `language_opt_in: true` metadata；H1 下方新增语言选择提示，明确中文引导为 opt-in；`agents/openai.yaml` 的 `default_prompt` 添加 opt-in 前缀。\n- 新增 `language_opt_in` metadata 字段至 SKILL.md frontmatter，供主机/审计工具检测。\n\n### Added\n- `agents/openai.yaml` 的 `short_description` 改为英文描述 + opt-in 说明。\n- `scripts/safe_io.py`: 新增 `safe_append(path, content)` 函数 — 使用 Python `open(path, 'a', encoding='utf-8')` 替代 PowerShell `Add-Content`，防止 GBK 编码污染 UTF-8 文件\n- `scripts/detect_gbk_contamination.py`: 新增检测和修复 UTF-8 文件中 GBK 编码污染的独立脚本（三种模式：`scan` 扫描目录检测污染文件、`inspect` 详细查看污染位置和字节上下文、`fix` 智能修复污染并支持 `--backup` 备份和 `--preview` 预览）\n- SKILL.md F 模式：新增陷阱 #8（PowerShell Add-Content GBK 编码污染），脚本工具表新增 `detect_gbk_contamination.py` 条目并更新 `safe_io.py` 条目，安全文件读写模板增加安全追加示例，\"不做什么\"清单增加 Add-Content 禁令\n- `scripts/init_env.ps1`: 脚本工具提示中加入 `detect_gbk_contamination.py` 条目并更新 `safe_io.py` 描述\n\n## [1.6.2] - 2026-07-10\n\n### Security\n- Removed hardcoded git commit permission from `reasonix.toml` — replaced with generic tool permissions (Bash, Read, Edit, Write) to eliminate appearance of hidden repository-modifying intent.\n- Changed `scripts/init_env.ps1` Git quotepath from `--global` to local scope (removed `--global` flag); removed unnecessary `core.autocrlf` setting.\n- Updated SKILL.md security disclosure to explicitly address `reasonix.toml` permission declarations and `init_env.ps1` local-only scope.\n\n## [1.6.1] - 2026-07-10\n\n### Security\n- Added `security` metadata to SKILL.md frontmatter — explicitly declares all file system capabilities (read/write, batch-edit, encoding-conversion, git-operations) so users and hosts can review before installation.\n- Added \"🛡️ 能力与安全披露\" (Capabilities & Security Disclosure) section to SKILL.md — transparently documents what the skill can do beyond prompting guidance.\n- Clarified F mode (Windows/PowerShell) is conditional and optional, not default behavior — macOS/Linux users and English-only workflows do not need it.\n- Added language disclosure: documentation is primarily in Chinese but the skill adapts to the user's interaction language.\n- Fixed `scripts/fix_encoding.py` docstring: changed \"默认创建 .bak 备份\" to \"需要 --backup 参数才会创建 .bak 备份\" to match actual implementation behavior.\n\n## [1.6.0] - 2026-07-10\n\n### Added\n- Added `scripts/` directory with 4 Python utility scripts + 1 PowerShell init script:\n - `scripts/safe_io.py` — safe file read/write module (handles UTF-8/UTF-16, write-to-file instead of print)\n - `scripts/fix_encoding.py` — batch file encoding detection and conversion to UTF-8 (4 modes: scan/preview/convert/check-replacement)\n - `scripts/verify_output.py` — verification result output to .txt file (replaces print to avoid GBK error)\n - `scripts/batch_edit.py` — apply multiple replacements to one file atomically (solves edit_file consecutive edit blocking)\n - `scripts/init_env.ps1` — Windows PowerShell environment init (git config, Python check, encoding health)\n- Added `.gitattributes` — proper line ending configuration for all file types\n- Updated SKILL.md F mode: references scripts/ tools in decision table and recommended workflow; adds \"脚本工具\" reference table\n\n## [1.5.0] - 2026-07-10\n\n### Added\n- Added **F. Windows/PowerShell 环境适配** task mode to SKILL.md for handling Windows PowerShell + Chinese text environment pitfalls — includes 7 known trap solutions, recommended workflow, safe file I/O template, and \"what not to do\" checklist.\n\n## [1.4.0] - 2026-04-27\n\n### Added\n- Added **E. 重大重构/架构调整** task mode to SKILL.md for handling systemic bugs, architecture mismatches, and large-scale refactoring — includes 5 trigger signals, 6-step flow (diagnosis → impact assessment → user-confirmed design → incremental migration → verified execution → cleanup), and dedicated output format.\n\n## [1.3.0] - 2026-04-27\n\n### Changed\n- Deduplicated README.md by removing content replicated from SKILL.md; README now serves as a slim landing page.\n- Trimmed package.json keywords from 24 to 7 (removed synonyms and sub-variants).\n- Shortened SKILL.md frontmatter description for clarity.\n- Relicensed from MIT to GPL-3.0 (copyleft license for stronger openness).\n\n### Fixed\n- Removed duplicate \"Added LICENSE\" entry from [1.1.0] in CHANGELOG.md — LICENSE was first added in v1.2.0.\n\n## [1.2.0] - 2026-04-27\n\n### Added\n- Added about description and topic tags to GitHub repository.\n- Added LICENSE file (MIT) to complete open source compliance.\n\n## [1.1.0] - 2026-04-27\n\n### Added\n- Added quick decision table mapping user request patterns → task mode → output format → tool preference.\n- Added \"精准提示词模板\" (precise prompt template) with compact goal/input/constraints/output format.\n- Added \"ZeroToken 强化模式\" section for explicit token-saving requests.\n- Added \"何时不使用 ZeroToken\" guard section.\n\n### Changed\n- Restructured SKILL.md: decision table at top, then core principles (5 from 8), then task modes with concrete tool mappings.\n- Tightened all sections—removed redundancy across core principles, task modes, and output rules.\n- Updated agents/openai.yaml default_prompt to match new decision-table-first flow.\n\n## [1.0.3] - 2026-04-27\n\n### Changed\n- Expanded package keywords for prompt engineering, context optimization, token budgeting, and agent workflow discovery.\n\n## [1.0.2] - 2026-04-27\n\n### Added\n- Added guidance for crafting the shortest precise prompt needed to solve the user's problem.\n- Added prompt framing rules for goal, input, constraints, output format, and acceptance criteria.\n\n## [1.0.1] - 2026-04-27\n\n### Changed\n- Changed the skill trigger guidance so ZeroToken is the default working discipline for suitable tasks.\n- Documented exceptions for exhaustive explanation, teaching-style expansion, brainstorming, and broad exploration.\n\n## [1.0.0] - 2026-04-27\n\n### Added\n- Added the initial `SKILL.md` with ZeroToken working discipline for token-efficient task execution.\n- Added `agents/openai.yaml` with a host-facing ZeroToken prompt preset.\n- Added minimal publishing files: `package.json`, `README.md`, and `CHANGELOG.md`.\n\nFile v1.16.0:docs/unicode-encoding-spec.md\n\n# Unicode 安全编码规范（项目执行版）\n\n> 本文件是「Unicode 安全编码规范」在本仓库的执行细则。\n> 生成或修改任何代码、配置、文档时，必须遵守本规范。\n> 配套工具见 `scripts/` 目录；仓库历史问题与根因见 `references/windows-powershell.md` 的「已知陷阱与解决方案」。\n\n## 总目标\n\n> 内部统一使用 Unicode，外部文本数据统一优先使用 UTF-8，\n> 所有编码边界显式声明编码，不依赖默认字符集，不进行无意义的重复转码。\n\n## 硬性规定（15 条）\n\n1. 所有源码、配置文件、模板文件、JSON、CSV、日志和文本文件统一使用 UTF-8 编码。\n2. 不要依赖操作系统、IDE、运行环境或系统区域设置的默认字符集。\n3. 任何涉及字符串、文件、网络请求、HTTP、数据库、JSON 序列化/反序列化的地方，都必须明确使用 UTF-8。\n4. 禁止在没有明确需求的情况下使用 GBK、GB2312、ANSI、Latin-1、Windows-1252 等编码。\n5. 禁止出现 UTF-8 编码后再按 GBK、ANSI 或其他编码解码的情况。\n6. 文件读取和写入时，应显式指定 UTF-8，而不是使用默认编码。\n7. Web 页面统一声明 UTF-8，例如：``\n8. HTTP 接口涉及文本内容时，应正确声明 UTF-8，例如：`Content-Type: application/json; charset=utf-8`\n9. 数据库应优先使用支持完整 Unicode 的字符集，例如 MySQL 使用 `utf8mb4`，同时确保数据库、表、字段和连接字符集保持一致。\n10. JSON 中的中文应正常作为 Unicode 字符处理，不要为了「防止乱码」而进行不必要的重复转码。\n11. 不要对已经是 Unicode 字符串的数据重复执行 encode/decode。\n12. 如果代码中存在 Base64、URL Encoding、HTML Entity、Unicode Escape 等编码操作，要明确区分「字符编码」和「数据转义」，不要混用。\n13. 修改已有项目时，先检查原有编码方式，避免因为强制转换造成已有数据损坏。\n14. 如果无法确定外部输入的字符编码，不要猜测，应在代码中增加明确的编码检测、参数配置或异常处理。\n15. 中文字符串、中文注释、中文文件名和中文接口数据都必须能够正确读取、存储、传输和显示。\n\n## Shell 选择规则（先探测系统参数）\n\n- 任何涉及命令行执行的任务，第一步先运行 `python scripts/detect_env.py`\n 获取当前系统参数并保存到 `.zerotoken/environment.json`（7 天有效期）。\n- **Windows 系统**一律使用 PowerShell 语法（`;` 链式 / `if ($?) {}` 条件链式），\n **禁用 bash**；PowerShell 版本以保存的探测结果为准\n （5.1 Desktop 与 7+ Core 的编码默认行为不同）。\n- **Linux/macOS** 使用 sh/bash/zsh 等 POSIX shell，不套用 PowerShell 规避规则。\n- 中文支持能力以探测结果 `console.cjk_capable` 为准：不支持时内容验证走文件而非终端显示。\n\n## 编码链路检查\n\n生成代码前，检查整个字符处理链路，确保每一个环节的编码一致：\n\n```\n输入数据 → 字符串处理 → 文件/数据库 → 网络传输 → API → 前端/终端显示\n```\n\n## 项目执行细则\n\n### Python 文件读写\n\n- 所有 `open()` 必须显式指定编码：读取用 `open(path, 'rb')` 二进制读后显式 decode，\n 或 `open(path, 'r', encoding='utf-8')`；写入一律 `open(path, 'w', encoding='utf-8')`。\n- **禁止** `errors='replace'` 静默替换损坏字符（会把中文无声变成 U+FFFD 替换字符）。\n 编码无法确定时必须显式抛错提示先检查原编码：\n 统一实现见 `scripts/safe_io.py` 的 `sniff_encoding` / `decode_bytes`\n （BOM → UTF-8 → GB18030，全部失败抛 `UnknownEncodingError`）。\n- 读取历史遗留文件（可能为 UTF-16 或 GB18030）用 `scripts/safe_io.py` 的 `safe_read`，\n 它会自动检测 BOM 并做安全解码；写入统一 UTF-8 无 BOM（`safe_write` / `safe_append`）。\n\n### 控制台输出（Windows 中文环境）\n\n- Python 3.7+：模块加载时显式 `sys.stdout.reconfigure(encoding='utf-8')`\n （`sys.stderr` 同理），不要依赖系统代码页（中文 Windows 默认 GBK/936）。\n- 兜底：无法重配置的流用 `safe_print`（`scripts/safe_io.py`），保证永不抛\n `UnicodeEncodeError`。\n- 终端显示：PowerShell 中配合 `chcp 65001` 查看中文输出；若仍乱码，属于终端显示层\n 问题，文件本身编码正确，用 `read_file` 工具验证内容。\n- **读取附件/文件**：Windows PowerShell 5.1 的 `Get-Content` 默认按 ANSI 代码页（GBK）\n 解码无 BOM 的 UTF-8 文件，含中文的附件会**显示乱码**（如 `鐗堟湰鍙?1.9.1`），但文件\n 未损坏。优先用 `read_file` 工具读取；必须在 PowerShell 中读时显式指定\n `Get-Content -Encoding UTF8`；附件是 GBK/UTF-16 等非 UTF-8 编码时用\n `safe_io.safe_read()` 自动检测转码。显示乱码≠文件损坏，禁止据此盲目转码。\n- **禁止**用 PowerShell `Add-Content` 向 UTF-8 文件追加中文（默认 GBK 写入会污染），\n 改用 Python `open(path, 'a', encoding='utf-8')` 或 `safe_io.safe_append`。\n\n### 文件写入编码矩阵（PS 5.1 实测）\n\n| 写入方式 | 默认编码 | 显式 `-Encoding UTF8` | 结论 |\n|----------|----------|----------------------|------|\n| `Set-Content` | GBK/ANSI；非 GBK 字符**静默写成 `?`**（emoji 实测变 `3F`） | UTF-8 **带 BOM** | ❌ 禁止用于任何非 ASCII 内容 |\n| `Add-Content` | 同上（追加即污染 UTF-8 文件）；且目标不以换行结尾时**不补换行导致粘连** | 带 BOM + 同样不补换行 | ❌ 禁止追加中文，统一用 `safe_io.safe_append()` |\n| `Out-File` / `>` 重定向 | UTF-16 LE（带 BOM） | UTF-8 带 BOM | ⚠️ 非 ASCII 时禁用默认行为 |\n| `[IO.File]::WriteAllText` / `AppendAllText` | **UTF-8 无 BOM**（.NET Core 3.0+/PS7 默认；5.1 下建议显式传编码） | — | ✅ PowerShell 内首选 |\n\n- PowerShell 中确需直接写 UTF-8 文本时统一用：\n `[IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`。\n- 跨脚本、含中文/emoji 的写入一律走 Python：`safe_io.safe_write()`（UTF-8 无 BOM +\n LF）/ `safe_append()`（自动补换行）。\n\n### PowerShell 脚本（.ps1）\n\n- **唯一例外**：`.ps1` 文件必须使用 **UTF-8 with BOM**。\n 原因：Windows PowerShell 5.1（系统自带）对无 BOM 文件按 ANSI 代码页（GBK）解码，\n 含中文的 UTF-8 无 BOM 脚本会乱码甚至解析异常。\n PowerShell 7+ 无此问题，但为兼容 5.1 统一带 BOM。\n- 已由 `scripts/init_env.ps1` 示范（首字节 `EF BB BF`）。\n\n### Node.js / HTTP\n\n- 请求头/响应头显式声明编码，例如\n `'Content-Type': 'application/json; charset=utf-8'`。\n- `fetch` / `readFileSync` / `writeFileSync` 显式传 `'utf-8'`；`JSON.stringify` 默认\n 保留 Unicode（不要 `escape` 转义中文）。\n- URL 编码、Base64、HTML Entity 属于**数据转义**，与字符编码无关，不得混用。\n\n### JSON\n\n- 中文作为普通 Unicode 字符处理：Python 用 `json.dumps(data, ensure_ascii=False)`，\n 写入文件时 `encoding='utf-8'`；不要为了「防乱码」做重复转码。\n\n### 数据库\n\n- 如引入数据库，使用 `utf8mb4`，并确保数据库、表、字段、连接字符集一致。\n\n## 仓库现有工具链\n\n| 工具 | 用途 |\n|------|------|\n| `scripts/safe_io.py` | 编码检测核心（sniff_encoding/decode_bytes）+ 安全读写（read_text/safe_read/safe_write/safe_append/write_result），safe_print 控制台兜底；unknown 显式抛 UnknownEncodingError |\n| `scripts/fix_encoding.py` | 扫描/转换文件编码为 UTF-8（scan / preview / convert / check-replacement） |\n| `scripts/detect_gbk_contamination.py` | 检测并修复 UTF-8 文件中的 GBK 污染（scan / inspect / fix） |\n| `scripts/batch_edit.py` | 一次多编辑（原子替换），复用 safe_io.read_text，不静默损坏 |\n| `scripts/verify_output.py` | 验证结果写入 UTF-8 文件（替代 print），grep_check 显式解码 |\n| `scripts/audit_encoding.py` | 全项目编码审计（UTF-8/BOM/替换字符/混合换行） |\n| `scripts/detect_env.py` | 环境探测与持久化：OS / Shell / 控制台编码 / 中文支持 / PowerShell 版本 / Git quotepath，结果存 `.zerotoken/environment.json`（7 天有效期），决定 F/G 模式与 Shell 选择 |\n| `scripts/init_env.ps1` | Windows 环境初始化（git quotepath、控制台 UTF-8、编码健康检查） |\n\n## 生成代码后的安全检查\n\n每次生成/修改代码后，额外执行一次：\n\n```powershell\npython scripts/audit_encoding.py --root . --out audit_result.txt\n```\n\n确认：\n1. 无 `non-utf8` 文件；\n2. 无 `替换字符`（U+FFFD）；\n3. 无混合换行（LF/CRLF 混用）；\n4. `.ps1` 文件带 BOM（审计单独列 `utf-8-sig` 属预期）。\n\nFile v1.16.0:skill-card.md\n\n## Description:\n\nZeroToken helps agents produce concise, direct answers, minimize unnecessary context and tool use, and provides optional encoding and Windows PowerShell utilities.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[phoenixlucky](https://clawhub.ai/user/phoenixlucky)\n\n### License/Terms of Use:\n\nGPL-3.0\n\n## Use Case:\n\nDevelopers and agent users use ZeroToken to guide assistants toward shorter, task-focused responses, bounded context gathering, and platform-aware command workflows. The skill also provides utility scripts for environment detection, UTF-8 safe file handling, encoding audits, version checks, and related repository maintenance tasks.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Search guidance can promote unverified local bridge scripts into executable tools.\n\nMitigation: Prefer registered host browser or search tools, avoid wildcard local bridge discovery, and require confirmation before using any bridge path.\n\nRisk: Encoding conversion and GBK repair utilities can modify repository files.\n\nMitigation: Use preview modes where available and keep backups or version-control checkpoints before converting or repairing important files.\n\nRisk: The skill may guide command execution or browser-tool usage in an agent host.\n\nMitigation: Review the skill before installation and require user confirmation for commands or browser actions that affect local files, credentials, or external accounts.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/phoenixlucky/skills/zerotoken-skill)\n- [README](README.md)\n- [Skill Definition](SKILL.md)\n- [Unicode Encoding Specification](docs/unicode-encoding-spec.md)\n- [Windows PowerShell Guidance](references/windows-powershell.md)\n- [Refactor Playbook](references/refactor-playbook.md)\n- [Search Guidance](references/search.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown and plain text with inline commands or code blocks when needed]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Concise, task-focused responses with optional command and file-edit guidance.]\n\n## Skill Version(s):\n\n1.16.0 (source: frontmatter, package.json, CHANGELOG)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.14.0: 30 files, 685248 bytes\n\nFiles: AGENTS.md (2625b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (582802b), CHANGELOG.md (22077b), docs/unicode-encoding-spec.md (8968b), LICENSE (35792b), package.json (595b), README.md (19304b), references/publishing-clawhub.md (3690b), references/refactor-playbook.md (2756b), references/search.md (2770b), references/tool-mapping.md (3102b), references/windows-powershell.md (13292b), scripts/audit_encoding.py (5756b), scripts/audit_skill.py (9601b), scripts/batch_edit.py (3690b), scripts/bump_version.py (4679b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_bump_version.py (3512b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/verify_output.py (5081b), scripts/zt.py (9598b), skill-card.md (2386b), SKILL.md (12194b), _meta.json (135b)\n\nFile v1.14.0:SKILL.md\n\n---\nname: zerotoken-skill\nversion: 1.14.0\ndescription: Token-efficient assistant discipline for concise, direct answers and minimal-context task execution. Use when the user asks for low-token / direct output or says「省 token / 简洁点 / 直接给结果 / 少废话 / 别解释」, or invokes this skill; includes optional file-encoding and Windows PowerShell utilities (single entry: `python scripts/zt.py help`).\nmetadata:\n security:\n capabilities:\n - filesystem-read: \"read local files\"\n - filesystem-write: \"write/modify local files\"\n - batch-edit: \"apply multiple text replacements to a single file\"\n - encoding-conversion: \"batch file encoding detection and conversion\"\n - gbk-contamination-detection: \"detect and repair GBK-contaminated UTF-8 files\"\n - git-operations: \"git config and commit operations\"\n permissions-declared: true\n language: \"回答语言跟随用户交互语言（用中文问就中文答）；文档正文为 zh-CN\"\n platforms: \"auto-detects OS at session start (detect_env.py): Windows/PowerShell -> Mode F, Linux/macOS -> Mode G\"\n references: \"细节按需读取 references/*.md（Windows 陷阱 / 重构手册 / 搜索规范 / 发布手册 / 工具映射）\"\n---\n\n# ZeroToken Skill\n\n> **语言**：回答语言跟随用户交互语言——用中文问就用中文答，用英文问就用英文答。\n> 平台环境由 `python scripts/detect_env.py` 自动识别，不需要用户声明语言或平台。\n> *(Answer in the user's language; environment detection is automatic.)*\n\n用最少必要 token 和最精准提示词完成任务。省 token ≠ 偷工减料；核心是减少无效上下文、无效解释、无效工具调用、无效输出。\n\n> **🛡️ 能力与安全披露**（安装前请确认符合你的安全策略）\n> 除提示词纪律外，本 Skill 还声明这些文件系统能力：\n> 读取/修改本地文件（`read_file`/`edit_file`/`write_file`）；批量替换与编码转换\n> （`scripts/batch_edit.py`、`fix_encoding.py`）；安全读写与追加（`scripts/safe_io.py`，\n> 规避 `Add-Content` 的 GBK 污染）；GBK 污染检测修复（`scripts/detect_gbk_contamination.py`）；\n> Git 配置（`scripts/init_env.ps1` 只改**当前仓库 local 配置**，不动全局）；\n> 环境探测结果写 `.zerotoken/environment.json`（7 天有效期，已 gitignore）。\n\n---\n\n## 📐 快速决策表\n\n| 用户请求特征 | 模式 | 首轮输出 | 工具偏好 |\n|---|---|---|---|\n| 问定义/翻译/短建议 | **A. 简单问答** | 1-5 句直接回答 | 直接输出，不跑工具 |\n| 单文件修复/配置调整 | **B. 代码小改** | 改动 + 验证结果 | `grep` → `read_file`(局部) → `edit_file` |\n| 跨模块功能/常规重构/CI | **C. 多文件任务** | 3-5 步短计划 | `glob` → `grep` → 分批 `read_file` |\n| 长文/日志/PR/文档总结 | **D. 大资料总结** | 要点 + 证据位置 | `read_file`(head+tail) → `grep`(关键行) |\n| 反复出同类 bug / 加功能越来越难 / 架构与需求不匹配 | **E. 重大重构/架构调整** | 问题诊断 + 目标方案 + 迁移路线图 | `explore` → 分批 `read_file`（详见 [`references/refactor-playbook.md`](references/refactor-playbook.md)） |\n| 用户明确说\"省 token\" | **ZeroToken 强化** | 最短可执行输出 | 同上，但跳过所有非必要探索 |\n| 用户说\"详细解释/教学\" | **➡ 退出 ZeroToken** | 常规详尽模式 | 不限 |\n| 系统是 Windows/PowerShell（detect_env.py 自动识别） | **F. Windows/PowerShell 环境适配** | 系统参数已保存，按陷阱规则调整工作流 | 详见 [`references/windows-powershell.md`](references/windows-powershell.md) |\n| 系统是 Linux/macOS（detect_env.py 自动识别） | **G. POSIX 标准工作流** | 按 POSIX 规则工作，禁用 PowerShell 语法 | 常规 shell 工具链（sh/bash/zsh） |\n\n> 工具名以当前宿主实际提供的为准；名字不同时见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n\n---\n\n## 🧭 核心原则\n\n1. **先分类，再预算** — 按上表决定上下文深度，不默认全量读取。\n2. **压缩提示词** — 目标 + 已知输入 + 约束 + 验收格式；只在缺失项会改变结果时追问。\n3. **渐进读取** — 先定位（`grep`/`glob`），再局部读，读完即停。大文件（70KB+）用 `read_file` 的 `offset` + `limit` 分页，避免被截断。\n4. **先给结果** — 结论或完成状态先行；解释、推理按需补充。\n5. **不复述** — 不重复用户问题、不写礼貌铺垫、不解释常识。\n6. **plan 只写顶层步骤，不写子 bullet** — 每个 phase 写 1 行（共 2-5 个），细节放说明文字里。宿主把 bullet 注册成独立待办时的规避细节、签收证据规则见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n7. **设置停止条件** — 已定位目标、必要调用方/数据源和验证方式后停止搜索；同一文件未变化时不重复读取。\n8. **先识别环境，再选 Shell** — 任何涉及命令行执行的任务，第一步：\n `python scripts/detect_env.py` → `.zerotoken/environment.json`（7 天有效期）。\n 之后所有命令按已保存的系统参数选择：Windows 一律 PowerShell（禁用 bash），\n Linux/macOS 用 sh/bash/zsh；中文支持能力以 `console.cjk_capable` 为准。\n\n---\n\n## 📚 参考文档（按需读取）\n\n| 文档 | 何时读 |\n|---|---|\n| [`windows-powershell.md`](references/windows-powershell.md) | 命中 F 模式；编码/乱码/GBK/PowerShell/附件读取问题 |\n| [`refactor-playbook.md`](references/refactor-playbook.md) | 命中 E 模式：诊断 → 方案 → 增量迁移 |\n| [`search.md`](references/search.md) | 需要外部资料、浏览器搜索、社交平台内容 |\n| [`tool-mapping.md`](references/tool-mapping.md) | 工具名与本文不符；宿主有 plan/待办/签收机制 |\n| [`publishing-clawhub.md`](references/publishing-clawhub.md) | **仅维护者**：发布新版本到 ClawHub |\n\n> 🔧 **工具入口：** `python scripts/zt.py help`（`zt.py check` 一键跑完全部校验）\n\n### 🚨 Windows 三条致命项（必守）\n\n1. **别用 `Add-Content` / `Set-Content` 写中文** — PS 5.1 默认按 GBK 写出，emoji 会静默变 `?`；改用 `safe_io.safe_write()` / `safe_append()`。\n2. **`Get-Content` 的中文乱码多是显示层假乱码** — 文件没坏；改用 `read_file` 或 `-Encoding UTF8`，禁止据乱码盲目转码重写。\n3. **命令行不内联中文**（`python -c \"中文\"`、含 `+`/反引号的参数）— 写 `.py` 脚本再 `python \"script.py\"` 执行。\n\n---\n\n## 📝 精准提示词模板\n\n```text\n目标：<要解决什么>\n输入：<数据/代码/错误/位置>\n约束：<不能做什么/必须满足什么>\n输出：<格式/字段/长度/验收标准>\n预算：<直接回答 / 最小读取 / 需要验证>（可省略，默认最小读取）\n```\n\n请求含糊时先用此模板提炼；只有缺关键输入才追问，一次只问 1 个问题。\n\n---\n\n## ⚔️ AI 编程总纲（尉缭子十原则）\n\n> **将军受命，君必先谋于庙，行令于廷，君身以斧钺授将。曰：左、右、中军皆有分职；若逾分而上请者死；军无二令，二令者诛；留令者诛；失令者诛。**\n\n核心不是军事，而是 **权限边界、单一指令、责任明确、执行一致**。与 ZeroToken 纪律互补：省 token 是效率，尉缭子是秩序。\n\n| # | 原则 | 要求 | 违反示例 |\n|---|---|---|---|\n| 1 | **先谋后动（谋于庙）** | 编码前先理解需求、明确目标、列出约束与方案，确认后再实现 | 边思考边改大量代码 |\n| 2 | **统一方案（行令于廷）** | 全仓库统一架构/命名/目录/接口/风格 | 一个问题多个实现、新旧逻辑混用 |\n| 3 | **职责明确（分职）** | 每层各司其职（UI→Service→Repository→DB），不得越级 | UI 直连数据库 |\n| 4 | **不得越权（逾分请者）** | 只改自己职责范围；修 SQL 不顺手改页面/接口/重构 | 顺手重构整个系统 |\n| 5 | **唯一命令（军无二令）** | 任何时刻只有一个最终需求；新需求先确认：废弃/覆盖/追加原需求 | 同时执行互相冲突的需求 |\n| 6 | **禁止旧令（留令者）** | 需求更新后旧方案立即失效，删除/替换/迁移，不留兼容层 | \"为了兼容以前\"偷偷保留旧代码 |\n| 7 | **严格执行（失令者）** | 已确认要求全部落实：功能/性能/注释/测试/边界情况 | 遗漏边界情况 |\n| 8 | **最小改动** | 修改范围越小越好，不影响已有功能；每次提交只解决一个问题 | 无关优化/重构 |\n| 9 | **可追溯** | 每次修改说明：为什么改、改了哪些文件/函数、影响、如何验证 | 修改历史无法追踪 |\n| 10 | **验证先于结束** | 编译/运行/需求/边界/回归全部验证通过才宣布完成 | 编码完就宣布结束 |\n\n**与任务模式的对应**：E 模式内置 #1（先诊断方案）、#8（不提前优化）、#10（每步验证）；\nB/C 模式动手前一句话确认需求 = #5；输出格式的「改动 / 验证 / 注意」= #9 + #10。\n\n### System Prompt 总纲\n\n> 臣缭以为：AI 编程，当先谋后动，后行其令。未明需求，不得编码；未定方案，不得实现。各模块各司其职，不得越权修改；一事唯遵一令，不得两令并行；新令既下，旧令即废，不得留存；既受其令，不得遗漏，不得擅改，不得借机重构。每次修改，应最小影响、责任明确、过程可追溯、结果可验证。凡编码者，以稳定为本，以一致为法，以执行为先。\n\n---\n\n## 🔄 任务模式要点\n\n- **A. 简单问答**：直接回答，不列计划、不问澄清（除非缺关键对象），不主动扩展背景。\n- **B. 代码小改**：定位 → 只读命中行附近 → 精准改 → 跑最小相关验证（lint / typecheck / 单测）。\n- **C. 多文件任务**：3-5 步短计划（每步 1 行，不用 bullet 子步骤）→ 每步只加载当前决策需要的文件 →\n 非关键问题记为事实清单而非当场修复 → 最终只报完成内容、关键改动、验证结果。\n- **D. 大资料总结**：先定输出目标（摘要/决策/风险/待办/差异/时间线）→ 保留数字、日期、结论、阻塞点 →\n 「要点 + 证据位置」代替大段引用。\n- **E. 重大重构**：见 [`refactor-playbook.md`](references/refactor-playbook.md)（先确认方案，再增量迁移）。\n- **F. Windows/PowerShell**：见 [`windows-powershell.md`](references/windows-powershell.md)（15 条陷阱 + 脚本工具）。\n- **G. POSIX**：sh/bash（macOS 默认 zsh），不套用 F 模式规则；文件编码仍统一 UTF-8\n （见 `docs/unicode-encoding-spec.md`）；非 UTF-8 locale 下中文可能显示乱码，验证走文件而非终端。\n\n---\n\n## ⚡ ZeroToken 强化模式\n\n当用户明确要求省 token / 简洁 / 减少上下文时，在对应模式基础上额外：\n\n- 跳过所有非必要探索（不 glob 全目录、不预览多个候选）\n- 工具调用次数压到最低（能 1 步不用 2 步）\n- 每次读取或工具调用前写明要验证的假设；得到答案即停止，不为\"保险\"重复调用\n- 输出只保留：做了什么 + 结果 + 用户下一步需要的操作（如果有）\n\n## 📤 输出格式\n\n```text\n已完成：...\n改动：...\n验证：...\n注意：... ← 无风险时省略\n```\n\n研究类：\n\n```text\n结论：...\n依据：...\n不确定：...\n下一步：...\n```\n\n重构/架构类（E 模式）的输出模板见 [`references/refactor-playbook.md`](references/refactor-playbook.md)。\n\n## 🚫 何时不使用 ZeroToken\n\n- 用户明确要求：详细解释、教学式展开、头脑风暴、广泛探索\n- 任务涉及：法律、医疗、金融决策、时间敏感信息（准确性优先，不省 token）\n- 用户明确说\"请详细说明\"\n\n## 🛡️ 质量底线\n\n- 不省略安全、准确性和用户明确要求\n- 不跳过必要测试来制造\"省 token\"假象\n- 不把猜测写成事实\n- 不用短答案掩盖不确定性\n\nFile v1.14.0:README.md\n\n\n\n# ⚡ ZeroToken Skill\n\n**让 Agent 用最少的 token 做最准的事**\n\n> ⚔️ **将军受命，君必先谋于庙，行令于廷，君身以斧钺授将。曰：左、右、中军皆有分职；若逾分而上请者死；军无二令，二令者诛；留令者诛；失令者诛。**\n>\n> 💬 **用不完，根本用不完，妈妈再也不用担心我缺 token 了。**\n\n[]()\n[](LICENSE)\n[]()\n
\n\n> **ZeroToken Skill** 是一套为 AI Agent 设计的**提示词纪律规范**——在不降低回答准确性的前提下，压缩无效上下文、无效解释、无效工具调用和无效输出，从而大幅降低 token 消耗和响应延迟。\n>\n> 它解决的核心问题是：Agent 在任务中经常过度读取、过度思考、过度输出，导致一次对话消耗成千上万不必要的 token。ZeroToken Skill 通过一套可执行的**模式决策表 + 行为约束 + 工具链策略**，让 Agent 在每一个任务环节都有明确的\"省 token 行为准则\"。\n>\n> 🎯 **目标：** 用最精准的提示，做最少的往返，产最精炼的结果。\n>\n> ✅ **适用于：** Reasonix / Codex CLI / OpenCode / Hermes / Cline 等主流 Agent 工具。一次学习，全平台受益。\n\n\n\n
\n\n
\n\n**⚡ 少即是多 — Less is More**\n\n
\n\nFile v1.14.0:_meta.json\n\n{\n \"ownerId\": \"kn7dpzpqn086by5pfg5sbf64zx80zr6m\",\n \"slug\": \"zerotoken-skill\",\n \"version\": \"1.14.0\",\n \"publishedAt\": 1789459515617\n}\n\nFile v1.14.0:references/publishing-clawhub.md\n\n# ClawHub 发布（skill 分发与同步）\n\n> 本文是**维护者手册**——使用者无需阅读。\n> 项目通过 ClawHub 分发：。\n> 以下规则来自实测发布过程，发布任何版本时必须遵守。\n\n## 关键事实\n\n- ❗ **ClawHub 不是 Git 端点** — 仓库远程 `clawhub` 只是发布页地址，\n `git fetch/push clawhub` 必然 404（`repository not found`）。**发布必须走 clawhub CLI**，\n 不能指望 git push。\n- 发布 CLI 由 pnpm 全局安装：`%LOCALAPPDATA%\\pnpm\\clawhub.CMD`\n （PowerShell `PATH` 未包含 pnpm 目录时直接调 `clawhub` 会「无法识别」，需用全路径）。\n- 登录状态用 `clawhub whoami` 验证（应输出 `phoenixlucky`）。\n- 新版本提交后 ClawHub 会跑**安全扫描**（异步、分钟级），**提交成功 ≠ 立即可见**。\n- 发布包内容以**发布时的工作区文件**为准：GitHub 提交 ≠ ClawHub 包同步。\n 打包范围由 `package.json` 的 `files` 字段声明（改目录结构时必须同步核对）。\n\n## 发布陷阱表（C 系，与 F 模式 #1-15 区分）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| C1 | **PowerShell `curl` 是别名** | `curl -s -o NUL https://...` 报「缺少参数 SessionVariable」 | PS 里 `curl` = `Invoke-WebRequest`（参数不兼容）；探测网络/API 一律用 **`curl.exe`** |\n| C2 | **`clawhub publish` 相对路径解析错误** | `publish .` 报 `Error: SKILL.md required` | CLI 默认 `--dir skills`（相对 workdir），相对路径找不到根目录 SKILL.md；✅ 传**绝对路径** |\n| C3 | **发布命令长时零输出** | 前台发布跑 2 分钟无输出被超时终止，ClawHub 无变化 | 上传 registry 需 5-6 分钟且**全程零输出**（易误判卡死）；✅ 用后台运行（`run_in_background`）+ 轮询等待 |\n| C4 | **安全扫描异步** | 发布提交成功（`Update submitted ... pending security scans before it becomes public`）但 registry/页面仍是旧版本号 | 平台规则：扫描通过才公开；✅ 用 `clawhub inspect phoenixlucky/zerotoken-skill --json` 或页面 `og:image` 复查，看到新版本号即已公开 |\n| C5 | **发布前工作区有未提交改动** | 工作区脏时发布，未提交改动**已随包上传 ClawHub** 但 GitHub 缺失，两端分叉 | ✅ 发布前先 `git status` 确认干净（或先提交）再发布；发布后复查 `git status` |\n| C6 | **带 source 参数触发上传 ticket 失效** | `publish ... --source-repo ... --source-commit ` 报 `Skill upload ticket is missing, used, or expired`（连续重试 + 等冷却无效） | 实测：**去掉 `--source-repo` / `--source-commit` 重试即成功**；source 元数据可发布后通过页面/GitHub 关联，不影响打包内容 |\n\n## 推荐发布时序（每次发布固定流程）\n\n```text\n0. git status 确认工作区干净；git log 记录待发布版本号\n1. 一键校验：python scripts/zt.py check\n （回归测试 + 编码审计 + 文档一致性 + 版本号三处联动；与 CI 同一条命令）\n2. git push origin main（GitHub 先行）\n3. clawhub publish <仓库绝对路径> --slug zerotoken-skill --owner phoenixlucky \\\n --version <新版本> --changelog \"<变更摘要>\" --no-input\n —— 先加 --dry-run 预览（应输出 Would publish @），\n 确认无误后移除 --dry-run 再次执行，并放后台运行（陷阱 C3）\n4. clawhub inspect phoenixlucky/zerotoken-skill 复查公开状态（异步，陷阱 C4）\n```\n\n> 版本号用 `python scripts/zt.py version ` 写入三处；`zt.py check` 与 CI 跑同一套校验。\n\nFile v1.14.0:references/refactor-playbook.md\n\n# E 模式参考：重大重构 / 架构调整\n\n> **触发信号**（满足任意一条即可进入此模式）：\n> - 同一模块反复修同一个类型的 bug，修了又犯\n> - 加一个小功能需要改 5+ 个文件，牵一发动全身\n> - 现有架构无法合理支持新需求，强行扩展会导致更深的 technical debt\n> - 测试覆盖率低、或测试需要大量 mock 才能跑，说明耦合度过高\n> - 代码逻辑纠缠不清，修改的「实际影响面」远超「预期影响面」\n>\n> 这是唯一**必须先确认方案再执行**的模式；其他模式识别即执行。\n\n## 流程\n\n1. **诊断根因，不治症状** — 先用跨文件探索工具（`explore`，或宿主提供的代码图工具）了解问题模块的全景（入口、调用链、数据流），定位系统性根源而非表面 bug。\n 产出：根因陈述（1-2 句话）。\n\n2. **评估影响面** — 摸清依赖关系：哪些模块依赖问题代码、哪些测试会受影响、是否有外部调用者。\n 产出：影响模块清单 + 风险等级。\n\n3. **设计方案 & 用户确认** — 输出 2-3 个候选方案的对比（每个含：核心思路、改动量、风险、迁移难度），\n 用 `ask` 让用户选择，**不要替用户做架构决策**。确认后再进入执行阶段。\n\n4. **制定增量迁移计划** — 将重构拆为可独立验证的小步，每步满足：\n - 可回滚（不破坏已有功能）\n - 可通过编译 + 已有测试\n - 新旧代码可共存过渡（strangler fig / feature flag / 适配层）\n 产出：`todo_write` 任务清单（顶层步骤，不含子 bullet）。\n\n5. **安全执行，每步验证** — 按计划逐步执行，每步后：\n - `lsp_diagnostics` 检查编译（宿主提供时）\n - 运行相关测试\n - 更新 `todo_write` 状态\n 发现计划外的依赖时暂停，补评估再继续。不得跳过验证走捷径。\n\n6. **清理收尾** — 删除废弃代码（不留「为了兼容以前」的旧实现，见总纲 #6）、移除过渡兼容层、\n 更新文档 / README / AGENTS.md。最后跑一次完整测试套件。\n\n## 输出模板（重构/架构类）\n\n```text\n问题：<根因 1-2 句>\n方案：<选定的方案简述>\n迁移计划：\n Step 1: <做什么> → 验证：<怎么验证>\n Step 2: ...\n风险：<已知风险和缓解措施>\n状态：进行中 | 已完成\n```\n\n## 关键原则\n\n- **先理解再动手**：E 模式允许较高的 token 消耗用于阅读和理解——诊断和设计方案阶段不做省 token 优化。\n- **不提前优化**：只重构当前确实有问题的部分，不顺手\"优化\"无关代码。\n- **留退出路径**：每一步都可以撤销或暂停，不做不可逆的一次性大改。\n\nFile v1.14.0:references/search.md\n\n# 搜索外部资料规范\n\n> 触发：任务需要外部资料（新闻、人物、公司、社交平台内容、实时信息等）。\n\n## 优先级\n\n| 优先级 | 方式 | 条件 |\n|--------|------|------|\n| 🥇 本地浏览器 MCP 桥 | 通过真实浏览器搜索（搜索引擎不限百度，按效果选） | 本地存在 MCP 桥脚本且服务在线 |\n| 🥈 宿主自带的抓取工具（如 `web_fetch`） | 备选，仅当浏览器桥不可用 | 无条件 |\n\n> **为什么优先真实浏览器？** 纯 HTTP 抓取依赖搜索引擎结果页，曾被反爬返回完全无关内容；\n> 真实浏览器搜索（Playwright/Chrome）结果精准可控。\n\n## 先探测，不要硬编码路径\n\n浏览器桥的调用入口**按实际安装位置探测**，不要假定某个 skill 名或目录存在。探测顺序：\n\n```text\n1. 宿主已注册的浏览器类 MCP 工具（如 mcp-server 提供的 search / navigate）\n2. 仓库或用户目录下已有的 MCP 桥：.reasonix/skills/*/mcp_call.py、mcp-bridge.js\n3. 都没有 → 回退到 web_fetch，或询问用户希望的检索方式\n```\n\n找到入口后，**Windows 上一律通过 Python 包装脚本调用**（`mcp_call.py` 等），\n不要在 PowerShell 里直接调 `node mcp-bridge.js`：\nPowerShell 的引号嵌套与 GBK 编码会破坏 JSON 参数（见 [`windows-powershell.md`](windows-powershell.md) 陷阱 5）。\n\n## 真实浏览器能搜什么\n\n| 场景 | 示例 | 形态 |\n|------|------|------|\n| 🔍 通用搜索 | 搜索新闻、人物、事件 | ` search 关键词` |\n| 🐦 社交媒体动态 | 搜微博、知乎、小红书上的内容 | ` search 微博 关键词` |\n| 🏢 公司/产品信息 | 查询公司背景、产品评测 | ` search 公司名 评价` |\n| 📰 最新资讯 | 今日热点、行业动态 | ` search 今日 热点` |\n\n> **无需为每个平台找专用 MCP server** — 真实浏览器通杀反爬严格的网站；搜索引擎按检索效果自由选择。\n\n**若浏览器桥不可用**：允许使用当前网络可用的其他搜索方式（如 `web_fetch`），\n不要因为首选方案不可用就放弃搜索。\n\n## 什么情况走抓取工具\n\n仅当以下条件**全部满足**时才回退：\n\n1. 浏览器桥入口不存在或 MCP 服务离线\n2. 目标网站没有反爬（非社交平台、非登录墙）\n3. 仅需获取静态页面内容（非 SPA 页面）\n\n## ❌ 禁用行为\n\n- **禁止用抓取工具直抓社交媒体（微博/知乎/小红书等）** — 全部有登录墙/反爬，100% 失败\n- **禁止自己写 Playwright/Puppeteer 脚本** — 已有现成的 MCP 桥，一行搞定\n- **禁止用抓取工具直连搜索引擎（Google/百度/Bing）** — 纯 HTTP 请求会被机器人检测拦截\n\nFile v1.14.0:references/tool-mapping.md\n\n# 工具名映射与宿主专属行为\n\n> 本 skill 描述的是**能力**，不是某个宿主的工具名。\n> 下表把本文档与 `SKILL.md` 中用到的能力映射到具体宿主工具；\n> 只调用当前宿主**实际提供**的等价工具，不要臆造名字。\n\n## 能力 → 工具名\n\n| 能力 | Reasonix | 其他宿主常见名 |\n|---|---|---|\n| 文本搜索（定位行） | `grep` | `search_content` / ripgrep / `grep` |\n| 文件枚举 | `glob` / `ls` | `directory_tree` / `find` / `list_dir` |\n| 局部读取 | `read_file`（`offset` + `limit`） | `read_file` / `open_file` |\n| 写入 / 编辑 | `write_file` / `edit_file` | `apply_patch` / `str_replace_editor` |\n| 同文件多处编辑 | `scripts/batch_edit.py`（宿主若提供 `multi_edit` 可优先用） | `multi_edit` |\n| 待办清单 | `todo_write` | `complete_step` / `update_plan` |\n| 跨文件探索 / 影响面 | `explore`（只读子代理） | `codegraph_context` / `codegraph_trace` / Task |\n| 结构化提问 | `ask` | `ask_user` |\n| 编译 / 类型检查 | `lsp_diagnostics` | `diagnostics` |\n| 网页抓取 | `web_fetch`（宿主提供时） | `fetch` / `browse` |\n\n> 代码图类工具（`codegraph_*`）若宿主提供，在 E 模式下优先于 `explore`——\n> 它给出的是调用链而非搜索命中。没有这类工具时，用 `explore` + `grep` 组合替代。\n\n## 宿主 verification 循环\n\n部分宿主（如带 AutoResearch 签收机制的宿主）会出现：验证证据已提供多次\n（git diff、文件检查、关键词检查），系统仍不接受，`stale_count` 持续累积。\n\n✅ 使用宿主提供的签收工具（如 `complete_step`，`kind: \"verification\"`）推进任务，\n而不是仅靠 `` 之类的文本块。\n✅ 签收证据的 `command` 字段必须与会话历史中的命令文本**完全一致**，否则被视为无效。\n✅ 宿主不提供签收工具时忽略本节——它是宿主行为，不是 Windows / 编码问题。\n\n## plan / todo 注册行为\n\n某些宿主的 plan 模式会把**每层 bullet 列表项**注册为独立待办项，且必须严格线性签收。\n规避方式：\n\n✅ 每个 phase 只写 1 行顶层步骤（共 2-5 个），细节写在说明文字中而非子 bullet。\n\n```text\n✅ 正确：\n1. safe_io.py 新增 safe_append 函数 — 用 open('a', encoding='utf-8') 替代 Add-Content\n\n❌ 错误（会生成 10+ 待办项）：\n1. safe_io.py 新增 safe_append\n - 实现函数\n - 更新文档字符串\n - 导出 __all__\n```\n\n若已陷入子步骤阻塞：优先用宿主的步骤调整机制（如 `complete_step({ step_index: N })`\n跳过中间项）直接签收当前卡住的项。\n\n**签收证据类型规则（宿主提供签收工具时）**\n\n- 工具写入的文件（`write_file` / `edit_file`）→ `files` 证据\n- 脚本写入的文件（如 Python 执行产物）→ `manual` 证据\n- `verification` 证据的 `command` 必须与会话历史中的命令文本完全一致\n- 每次工具调用只签一个步骤，按顺序推进（部分宿主限制：每轮只允许一个成功签收）\n\nFile v1.14.0:references/windows-powershell.md\n\n# F 模式参考：Windows / PowerShell 环境适配\n\n> **触发**：`python scripts/detect_env.py` 报告 `os.name == \"windows\"` 且推荐 shell 为 PowerShell。\n> 自动启用，**无需用户请求**，也不要求任务涉及中文。\n> 系统参数（OS 版本、控制台代码页、中文支持、PowerShell 发行版、Git quotepath）在探测时\n> 存入 `.zerotoken/environment.json`（7 天有效期），后续所有命令选择以保存的参数为准。\n>\n> **不适用**：macOS / Linux → 见 `SKILL.md` 的 G 模式，不要套用本文的规避规则。\n\n## 先决定：用编辑工具还是 Python 脚本\n\n| 情形 | 做法 |\n|---|---|\n| 纯 ASCII 内容、单处改动、文件本身是 UTF-8 | `edit_file` 直接改（B 模式默认路径） |\n| 内容含中文 / emoji / 特殊符号（`+`、反引号、`\\r\\n`） | `write_file` 写 `.py` 脚本，再 `python \"script.py\"` |\n| 同一文件需要多处改动（≥2 处） | 一个 Python 脚本一次完成，或用 `scripts/batch_edit.py` |\n| 批量编码转换 / GBK 污染修复 | `scripts/fix_encoding.py` / `scripts/detect_gbk_contamination.py` |\n| 命令参数本身含中文 | 写 `.py` 脚本执行，**不要**在命令行内联中文 |\n\n判定理由：PowerShell 命令行是编码 + 转义的双重雷区（见陷阱 1 / 8 / 11），\n而 Python 脚本的「写入脚本文件」和「执行脚本」两条路径都受 UTF-8 控制。\n\n## 已知陷阱与解决方案（15 条）\n\n| # | 陷阱 | 症状 | 解决方案 |\n|---|------|------|----------|\n| 1 | **PowerShell 与中文文本冲突** | `bash` 工具传中文给 PowerShell，`+` 被解析为字符串拼接运算符；反引号 `` ` `` 被识别为转义字符；含中文的 PowerShell 字符串报 `Missing ')'` 语法错误 | ❌ 不要直接在 `bash` 命令中嵌入含 `+` 的中文
✅ 改为 `write_file` 写 `.py` 脚本文件，再用 `python \"script.py\"` 执行 |\n| 2 | **文件编码不一致** | 部分文件（如旧中文 Markdown）实际是 UTF-16 编码；Python 默认 UTF-8 读取抛 `UnicodeDecodeError`；旧文件中已有因编码损坏产生的替换字符（U+FFFD），导致字符串精确匹配失败 | ✅ 统一采用 UTF-8 编码读写
✅ 安全读取方案见下文的「安全文件读写模板」 |\n| 3 | **edit_file 同文件连续编辑阻塞**（宿主行为，与系统无关） | 同一文件的多处修改，第一次 `edit_file` 后第二次被拒，错误：`fresh read required — was already modified earlier this turn` | ✅ 对同一文件的多处修改，一次性用 Python 脚本完成
✅ 或用宿主提供的多编辑工具一次传入多个替换（≤5 个以内）
✅ 维护一个更新脚本，执行后统一验证 |\n| 4 | **Git 中文文件名转义显示** | `git diff --stat` 显示 `\\xxx\\xxx` 编码序列，无法直接阅读中文文件名 | ✅ 先执行 `git config core.quotepath false` |\n| 5 | **PowerShell → Node.js 中文 JSON 参数断裂** | 调用 `node mcp-bridge.js call tools/call '{\"name\":\"x\",\"arguments\":{\"url\":\"中文\"}}'` 时，中文导致 JSON 解析失败 | ✅ **不要直接调 `node mcp-bridge.js`**
✅ 改用 Python 包装脚本（本地 MCP 桥自带 `mcp_call.py`），其内部已用 `json.dumps()` 正确序列化 |\n| 6 | **宿主 verification 死循环**（宿主行为，与系统无关） | 验证证据已提供多次（git diff、文件检查、关键词检查），但系统始终不接受；`stale_count` 持续累积 | ✅ 见 [`tool-mapping.md`](tool-mapping.md) 的「宿主 verification 循环」 |\n| 7 | **Python 控制台输出中文失败** | Python 的 `print()` 在 PowerShell 控制台下因 GBK 编码报错：`UnicodeEncodeError: 'gbk' codec can't encode character` | ✅ 不直接 `print()`，写入 `.txt` 文件后用 `read_file` 查看
✅ 使用 `with open(out_path, 'w', encoding='utf-8') as f: f.write(result)` |\n| 8 | **PowerShell 中 `\\r\\n` 转义** | PowerShell 脚本中 `` `r`n `` 的反引号被解释为换行转义符，导致语法错误 | ✅ 不在 PowerShell 中拼接含换行的多语言文本
✅ 改用 Python 的 `\\n` 处理换行 |\n| 9 | **PowerShell Add-Content 使用 GBK 编码污染 UTF-8 文件** | 用 `Add-Content` 向 UTF-8 文件追加中文后，新内容变为乱码（GBK 字节被误读为 UTF-8，出现 U+FFFD 替换字符），文件末尾出现 `0x81` 等无效 UTF-8 字节
根因：PowerShell 的 `Add-Content` 默认使用系统区域编码（Windows 中文版为 GBK）写入 | ❌ **禁止直接使用 PowerShell Add-Content 追加含中文的内容**
✅ 使用 Python 安全追加：`open('file.md', 'a', encoding='utf-8').write('内容')`
✅ 或用 `safe_io.py` 的 `safe_append()` 函数
✅ 已污染的文件用 `dete\n\nArchive v1.13.2: 21 files, 665407 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (582802b), CHANGELOG.md (18930b), docs/unicode-encoding-spec.md (8983b), LICENSE (35118b), package.json (532b), README.md (17688b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (3690b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/verify_output.py (5081b), skill-card.md (2209b), SKILL.md (34144b), _meta.json (135b)\n\nArchive v1.13.1: 21 files, 665312 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (582802b), CHANGELOG.md (18523b), docs/unicode-encoding-spec.md (8983b), LICENSE (35118b), package.json (532b), README.md (17688b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (3690b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/verify_output.py (5081b), skill-card.md (2335b), SKILL.md (34144b), _meta.json (135b)\n\nArchive v1.13.0: 21 files, 665094 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (582802b), CHANGELOG.md (17908b), docs/unicode-encoding-spec.md (8983b), LICENSE (35118b), package.json (532b), README.md (17498b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (3690b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/verify_output.py (5081b), skill-card.md (2489b), SKILL.md (34144b), _meta.json (135b)\n\nArchive v1.12.0: 23 files, 713105 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), assets/zerotoken-banner.webp (582802b), CHANGELOG.md (16649b), clawhub_page.html (139976b), clawhub_publish.html (58140b), docs/unicode-encoding-spec.md (8983b), LICENSE (35118b), package.json (532b), README.md (17376b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (3690b), scripts/detect_env.py (15400b), scripts/detect_gbk_contamination.py (14951b), scripts/fix_encoding.py (9123b), scripts/init_env.ps1 (4418b), scripts/safe_io.py (10004b), scripts/test_detect_env.py (4138b), scripts/test_safe_io.py (4246b), scripts/verify_output.py (5081b), skill-card.md (2317b), SKILL.md (30881b), _meta.json (135b)\n\nArchive v1.10.0: 18 files, 63416 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), CHANGELOG.md (10995b), docs/unicode-encoding-spec.md (6246b), LICENSE (35118b), package.json (532b), README.md (16239b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (5174b), scripts/detect_gbk_contamination.py (15466b), scripts/fix_encoding.py (9638b), scripts/init_env.ps1 (2717b), scripts/safe_io.py (5653b), scripts/test_safe_io.py (638b), scripts/verify_output.py (5596b), skill-card.md (2317b), SKILL.md (25047b), _meta.json (135b)\n\nArchive v1.9.1: 19 files, 62018 bytes\n\nFiles: AGENTS.md (829b), agents/openai.yaml (254b), CHANGELOG.md (10119b), docs/unicode-encoding-spec.md (6204b), LICENSE (35118b), package.json (531b), README.md (13565b), reasonix.toml (186b), scripts/audit_encoding.py (4792b), scripts/batch_edit.py (5174b), scripts/detect_gbk_contamination.py (15466b), scripts/fix_encoding.py (9638b), scripts/init_env.ps1 (2717b), scripts/safe_io.py (5653b), scripts/test_safe_io.py (638b), scripts/verify_output.py (5596b), skill-card.md (2353b), SKILL.md (24638b), _meta.json (134b)\n\nArchive v1.9.0: 17 files, 54272 bytes\n\nFiles: AGENTS.md (177b), agents/openai.yaml (254b), CHANGELOG.md (9035b), LICENSE (35118b), package.json (531b), README.md (13907b), reasonix.toml (1257b), scripts/batch_edit.py (4277b), scripts/detect_gbk_contamination.py (15158b), scripts/fix_encoding.py (9322b), scripts/init_env.ps1 (2747b), scripts/safe_io.py (4728b), scripts/test_safe_io.py (638b), scripts/verify_output.py (5106b), skill-card.md (2362b), SKILL.md (24449b), _meta.json (134b)","readmeExcerpt":"Skill: ZeroToken Owner: phoenixlucky Summary: Token-efficient, safe agent execution Tags: agent-discipline:1.6.0, latest:1.17.0, token-efficient:1.6.0, zerotoken:1.6.0 Version history: v1.17.0 | 2026-09-20T07:34:38.599Z | user 安全：移除未受信任桥脚本探测与执行（修复审计 T07）并补充第三方数据外发提示；audit_encoding 移除 .env 避免误报；收窄 SKILL.md 自动触发条件；fix_encoding 无 --backup 时告警 v1.16.0 | 2026-09-20T05:42:26.932Z | user 新增站内锚点与脚本引用审计；回归测试自动发现；README 瘦身 45%","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"目标：<要解决什么>\n输入：<数据/代码/错误/位置>\n约束：<不能做什么/必须满足什么>\n输出：<格式/字段/长度/验收标准>\n预算：<直接回答 / 最小读取 / 需要验证>（可省略，默认最小读取）"},{"language":"text","snippet":"已完成：...\n改动：...\n验证：...\n注意：... ← 无风险时省略"},{"language":"text","snippet":"结论：...\n依据：...\n不确定：...\n下一步：..."},{"language":"text","snippet":"0. git status 确认工作区干净；git log 记录待发布版本号\n1. 一键校验：python scripts/zt.py check\n （回归测试 + 编码审计 + 文档一致性 + 版本号三处联动；与 CI 同一条命令）\n2. git push origin main（GitHub 先行）\n3. clawhub publish <仓库绝对路径> --slug zerotoken-skill --owner phoenixlucky \\\n --version <新版本> --changelog \"<变更摘要>\" --no-input\n —— 先加 --dry-run 预览（应输出 Would publish @），\n 确认无误后移除 --dry-run 再次执行，并放后台运行（陷阱 C3）\n4. clawhub inspect phoenixlucky/zerotoken-skill 复查公开状态（异步，陷阱 C4）"},{"language":"text","snippet":"问题：<根因 1-2 句>\n方案：<选定的方案简述>\n迁移计划：\n Step 1: <做什么> → 验证：<怎么验证>\n Step 2: ...\n风险：<已知风险和缓解措施>\n状态：进行中 | 已完成"},{"language":"text","snippet":"1. 回退到宿主自带的静态抓取工具（如 web_fetch）\n2. 都不可用 → 询问用户希望的检索方式"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: zerotoken-skill\nversion: 1.17.0\ndescription: Token-efficient assistant discipline for concise, direct answers and minimal-context task execution. Use only when the user explicitly requests low-token / direct output (e.g. says「省 token」「直接给结果」) or invokes this skill by name; includes optional file-encoding and Windows PowerShell utilities (single entry: `python scripts/zt.py help`).\nmetadata:\n security:\n capabilities:\n - filesystem-read: \"read local files\"\n - filesystem-write: \"write/modify local files\"\n - batch-edit: \"apply multiple text replacements to a single file\"\n - encoding-conversion: \"batch file encoding detection and conversion\"\n - gbk-contamination-detection: \"detect and repair GBK-contaminated UTF-8 files\"\n - git-operations: \"git config and commit operations\"\n permissions-declared: true\n language: \"回答语言跟随用户交互语言（用中文问就中文答）；文档正文为 zh-CN\"\n platforms: \"auto-detects OS at session start (detect_env.py): Windows/PowerShell -> Mode F, Linux/macOS -> Mode G\"\n references: \"细节按需读取 references/*.md（Windows 陷阱 / 重构手册 / 搜索规范 / 发布手册 / 工具映射）\"\n---\n\n# ZeroToken Skill\n\n> **语言**：回答语言跟随用户交互语言——用中文问就用中文答，用英文问就用英文答\n> （语言可自选；本文件正文用 zh-CN 只是默认，不强制）。\n> 平台环境由 `python scripts/detect_env.py` 自动识别，不需要用户声明语言或平台。\n> *(Answer in the user's language; environment detection is automatic.)*\n\n用最少必要 token 和最精准提示词完成任务。省 token ≠ 偷工减料；核心是减少无效上下文、无效解释、无效工具调用、无效输出。\n\n> **🛡️ 能力与安全披露**（安装前请确认符合你的安全策略）\n> 除提示词纪律外，本 Skill 还声明这些文件系统能力：\n> 读取/修改本地文件（`read_file`/`edit_file`/`write_file`）；批量替换与编码转换\n> （`scripts/batch_edit.py`、`fix_encoding.py`）；安全读写与追加（`scripts/safe_io.py`，\n> 规避 `Add-Content` 的 GBK 污染）；GBK 污染检测修复（`scripts/detect_gbk_contamination.py`）；\n> Git 配置（`scripts/init_env.ps1` 只改**当前仓库 local 配置**，不动全局）；\n> 环境探测结果写 `.zerotoken/environment.json`（7 天有效期，已 gitignore）。\n\n---\n\n## 📐 快速决策表\n\n| 用户请求特征 | 模式 | 首轮输出 | 工具偏好 |\n|---|---|---|---|\n| 问定义/翻译/短建议 | **A. 简单问答** | 1-5 句直接回答 | 直接输出，不跑工具 |\n| 单文件修复/配置调整 | **B. 代码小改** | 改动 + 验证结果 | `grep` → `read_file`(局部) → `edit_file` |\n| 跨模块功能/常规重构/CI | **C. 多文件任务** | 3-5 步短计划 | `glob` → `grep` → 分批 `read_file` |\n| 长文/日志/PR/文档总结 | **D. 大资料总结** | 要点 + 证据位置 | `read_file`(head+tail) → `grep`(关键行) |\n| 反复出同类 bug / 加功能越来越难 / 架构与需求不匹配 | **E. 重大重构/架构调整** | 问题诊断 + 目标方案 + 迁移路线图 | `explore` → 分批 `read_file`（详见 [`references/refactor-playbook.md`](references/refactor-playbook.md)） |\n| 用户明确说\"省 token\" | **ZeroToken 强化** | 最短可执行输出 | 同上，但跳过所有非必要探索 |\n| 用户说\"详细解释/教学\" | **➡ 退出 ZeroToken** | 常规详尽模式 | 不限 |\n| 系统是 Windows/PowerShell（detect_env.py 自动识别） | **F. Windows/PowerShell 环境适配** | 系统参数已保存，按陷阱规则调整工作流 | 详见 [`references/windows-powershell.md`](references/windows-powershell.md) |\n| 系统是 Linux/macOS（detect_env.py 自动识别） | **G. POSIX 标准工作流** | 按 POSIX 规则工作，禁用 PowerShell 语法 | 常规 shell 工具链（sh/bash/zsh） |\n\n> 工具名以当前宿主实际提供的为准；名字不同时见 [`references/tool-mapping.md`](references/tool-mapping.md)。\n\n---\n\n## 🧭 核心原则\n\n1. **先分类，再预算** — 按上表决定上下文深度，不默认全量读取。\n2. **压缩提示词** — 目标 + 已知输入 + 约束 + 验收格式；只在缺失项会改变结果时追问。\n3. **渐进读取** — 先定位（`grep`/`glob`），再局部读，读完即停"},{"path":"README.md","content":"\n\n# ⚡ ZeroToken Skill\n\n**让 Agent 用最少的 token 做最准的事**\n\n> ⚔️ **先谋后动，军无二令 —— 省 token 是效率，尉缭子是秩序。**\n>\n> 💬 **用不完，根本用不完，妈妈再也不用担心我缺 token 了。**\n\n[]()\n[](LICENSE)\n[]()\n[](https://github.com/phoenixlucky/zerotoken-skill/actions/workflows/ci.yml)\n\n
\n\n> **ZeroToken Skill** 是一套为 AI Agent 设计的**提示词纪律规范**——在不降低回答准确性的前提下，压缩无效上下文、无效解释、无效工具调用和无效输出。\n>\n> 它解决的核心问题是：Agent 在任务中经常过度读取、过度思考、过度输出，导致一次对话消耗成千上万不必要的 token。本 Skill 通过一套可执行的**模式决策表 + 行为约束 + 工具链策略**，让 Agent 在每一个任务环节都有明确的\"省 token 行为准则\"。\n>\n> 🎯 **目标：** 用最精准的提示，做最少的往返，产最精炼的结果。\n>\n> ✅ **适用于：** Reasonix / Codex CLI / OpenCode / Hermes / Cline 等主流 Agent 工具。一次学习，全平台受益。\n\n\n\n
\n\n