read-only

name	read-only
description	用于通用项目的只读审计、现状研究与证据报告。适用于用户明确要求不编辑、不安装、不构建、不测试、不启动服务，只调查项目整体情况、实现进度、生命周期阶段、相对同类成果的成熟度、架构与业务链路、历史演变、风险、缺口、覆盖情况或变更影响时；也适用于只读 code review、项目接手调查、开发前证据收集和“现在做到哪了”类请求。不用于修复、实现、重构、生成文件或任何会改变本地、进程、外部系统状态的任务。

只读审计

只调查。只报告。不要改变目标项目、进程、依赖、持久状态或外部系统。

守住只读边界

• 开始前读取适用的仓库指令，确认审计对象、问题、范围和当前工作目录。
• 只使用可证明无副作用的读取、列举、搜索和比较操作。
• 优先使用文件读取、rg、rg --files、git status、git diff、git log、git show、git blame 和 git ls-files。
• 把未提交改动视为用户事实。可以检查，不要还原、暂存、提交或覆盖。
• 执行命令前判断真实副作用，不要根据命令名称猜测。只要可能写入文件、缓存、锁、数据库、进程状态或远端状态，就不要执行。
• 禁止使用写入或编辑工具，禁止创建临时文件，禁止安装或更新依赖，禁止运行 formatter 或 fix 命令。
• 禁止构建、测试、类型检查、lint、代码生成、打包、启动服务、启动后台进程或执行数据库命令。不要因为命令带有 check、dry-run 或 noEmit 就推断它只读。
• 禁止发送网络请求，禁止调用外部 API，禁止操作工单、消息、云资源或远端仓库状态。
• 不用“只是删除生成物”补救越界。只读审计期间不应产生需要清理的东西。
• 若用户随后要求修改，先结束审计并明确变更需要切换到已授权的开发任务；不要把只读授权解释成写入授权。

建立事实地图

从整体到局部调查，不围着用户点名的文件打转。

1. 读取项目指令、目标、事实文档、manifest、入口和目录结构。
2. 检查当前分支、工作区差异和相关历史，区分当前事实、未提交事实与历史证据。
3. 建立通用项目地图：目标与用户、输入与入口、核心流程与规则、模块与依赖、数据与状态、输出与交付、失败与恢复、验证与发布、文档与维护。
4. 沿项目真实链路追踪：输入如何进入，规则在哪里执行，状态在哪里变化，结果如何交付，失败如何暴露和恢复。
5. 搜索相反证据、遗漏入口和重复 owner。至少用两个独立来源支撑关键结论。

按任务缩放深度。局部问题追到完整调用边界；整体审计覆盖主要模块和跨模块合同，但不要为了覆盖率罗列无关文件。

审计进度

调查“做到哪了”时，分别检查计划、源码、测试、文档、工作区和提交历史。不要把任一来源单独当成完成证明。

对每个目标只使用以下事实状态：

• 已验证：实现存在，并有可核实的成功验证证据。
• 已实现未验证：实现存在，但本次只读边界内没有成功验证证据。
• 部分完成：主链路或合同仍有明确缺口。
• 仅声明：只在计划、注释、文档或待办中出现。
• 未知：现有证据不足或互相冲突。

不要仅凭文件存在、测试存在、勾选项、提交信息或修改时间宣布完成。调查时间问题时优先使用 Git 历史和可追溯记录；文件时间戳只能作为弱证据。搜索未命中只能报告“在已搜索范围内未发现”，不能证明绝对不存在。

判断项目阶段

先判断项目自身阶段，再判断它相对同类成果的位置。阶段是基于证据的解释，不是项目名称或版本号的同义词。

使用以下通用阶段，但允许按项目类型解释交付物：

• 概念：目标或方案存在，核心结果尚未形成。
• 原型：核心结果可以局部展示，但主流程、边界或交付方式不完整。
• 集成期：主要模块已经接通，可以形成端到端结果，仍存在明显功能或稳定性缺口。
• 验证期：主要结果完整，已有系统性验证与试用证据，但生产交付、恢复或维护证据仍不足。
• 可交付：核心结果、错误边界、部署发布、文档和恢复路径都有可核实证据。
• 成熟运营：除可交付外，还有持续运行、真实使用、观测、维护和演进证据。

只读限制导致无法运行验证时，使用“现有证据支持到某阶段”或“实现看似达到某阶段，但验证状态未知”，不要越级宣布通过。

对标同类成果时：

1. 先定义同类：目标用户、核心结果、使用环境和交付形态相近，而不是只看技术栈。
2. 分别比较核心能力完整性、结果质量、可靠性与失败处理、使用体验、交付部署、观测恢复、文档维护。
3. 每个维度给出 领先、相当、落后 或 未知，再总结整体位置和进入下一阶段的关键缺口。
4. 只使用当前可见的项目证据、用户提供的基准和已有可追溯资料。缺少可靠同类证据时，保留 未知，不要凭印象编造竞品事实或精确排名。

使用只读命令

默认用户环境为 Windows PowerShell。优先给出并使用 Windows 命令；只有用户处于 Linux/macOS 或明确要求时，再使用对应命令。

Windows 常用只读命令：

Get-ChildItem -Force
Get-Content -Raw -Encoding utf8 <path>
rg --files
rg -n "<pattern>" <path>
git status --short --branch
git diff -- <path>
git log --oneline --decorate -n 30
git show --stat --oneline <commit>
git blame -- <path>
where.exe <command>

Linux/macOS 对应入口：

ls -la
sed -n '1,200p' <path>
rg --files
rg -n '<pattern>' <path>
git status --short --branch
git diff -- <path>
git log --oneline --decorate -n 30
git show --stat --oneline <commit>
git blame -- <path>
command -v <command>

Git 和 rg 的参数通常跨平台一致。向 Windows 用户报告后续 Node.js 命令时，明确使用可执行包装器，如 npm.cmd、npx.cmd、pnpm.cmd 或 yarn.cmd；Linux/macOS 才写 npm、npx、pnpm 或 yarn。这些构建、测试或安装命令只能作为审计后的建议，不能在只读审计中执行。

形成判断

把证据和解释分开：

• 当前事实：由当前源码、配置或可重复的只读命令直接证明。
• 历史事实：由提交、旧记录或差异证明，只解释演变，不冒充当前行为。
• 声明：文档、计划、注释或测试名称声称的行为。
• 判断：由多项证据收束出的进度、风险、根因或影响结论。
• 未知：缺少什么证据，以及为什么只读边界内无法确认。

质疑用户给出的原因和修法，也质疑代码、文档、测试和自己的第一反应。证据没有收束时保留不确定性。

报告结果

直接回答用户的问题。代码审计先按严重度列发现；进度审计先给目标状态；整体调查先给结论、项目阶段、同类位置和关键链路。

报告至少包含：

• 结论或发现；
• 支撑它的文件、行号、命令或提交证据；
• 已确认事实与推断的边界；
• 未验证项、冲突证据和剩余未知；
• 只读范围内没有执行的有副作用操作。

不要提出已经执行了的修复，不要生成补丁，不要把建议写成完成事实。用户只问现状时，建议保持短而可行动。