diff --git a/CHANGELOG.md b/CHANGELOG.md index f783082..ca8e4aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,9 @@ ## Unreleased -No changes yet. +### Added + +- Optional Simplified/Traditional Chinese repository overviews, core user guides and limitation summaries, with reciprocal language links and an explicit source-revision/coverage note. Advanced references remain English; CLI messages, JSON fields, rule semantics and the published v0.23.0 distributions are unchanged. ## v0.23.0 diff --git a/README.md b/README.md index 0f485fe..2de590c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # AgentConfigScore +English | [简体中文](https://github.com/LE0-Lin/AgentConfigScore/blob/main/README.zh-CN.md) | [繁體中文](https://github.com/LE0-Lin/AgentConfigScore/blob/main/README.zh-TW.md) +

AgentConfigScore A 100

@@ -610,13 +612,17 @@ The Action emits outputs before returning its final regression status. Use `if: - [x] source and installed-package gates before publication - [x] user guide, exit-code reference and troubleshooting - [x] versioned English core package with release notes and compatibility guidance -- [ ] optional Simplified and Traditional Chinese documentation and README language switch +- [x] optional Simplified and Traditional Chinese core documentation and README language switch - [ ] optional semantic contradiction plugin See [release readiness and the localization sequence](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/release-readiness.md). Semantic extensions are optional; they are not a prerequisite for the core deterministic CI checker. +The localized core overview, user guide and limitations are available separately; +advanced references and research documents remain English. See the +[translation scope and maintenance note](https://github.com/LE0-Lin/AgentConfigScore/blob/main/docs/translations.md). + ## Development ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..0dd9e42 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,112 @@ +# AgentConfigScore + +[English](README.md) | 简体中文 | [繁體中文](README.zh-TW.md) + +为 AI 编程助手的指令文件提供本地检查与 PR 回归门禁。 + +![AgentConfigScore 演示](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif) + +AgentConfigScore 检查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等配置，并比较改动前后的基线，回答一个具体问题：**这次改动是否引入了已知规则能检测到的风险？** + +它是确定性检查器，不是 AI 评委。**A 100 只表示没有命中生效的规则，不表示指令有用、语义完美或安全无误。** 中文文档也不意味着检测器已经能够理解任意中文指令。 + +## 快速开始 + +需要 Python 3.10+。`diff` 还需要 Git；普通目录扫描和两个目录之间的 `compare` 不需要 Git。 + +```bash +python -m pip install --upgrade agent-config-score +agent-config-score --version +agent-config-score init +agent-config-score doctor +agent-config-score diff +``` + +在自己的仓库目录中运行。`init` 会生成 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`；检查后提交这两个文件，后续 PR 即可自动检查。它不会替你编写或重写指令文件，也不会默认覆盖冲突的已有配置。 + +`acs` 是短命令别名。v0.23.0+ 还可以使用 `python -m agent_config_score`，避免终端 PATH 没有找到命令的问题。 + +- [简体中文使用指南](docs/zh-CN/user-guide.md)：安装、基线、报告、退出码与排错。 +- [分数含义与限制](docs/zh-CN/limitations.md)：先了解什么能检出、什么仍可能漏掉。 +- [完整英文文档索引](docs/README.md)：进阶接口与研究资料。 + +## 为什么采用回归检查 + +现有仓库不必先达到 100 分才能接入。如果基线是 72 分，没有退步的改动可以通过；降低分数或引入新错误的改动则依据配置被拦截。 + +初始化后的核心策略如下： + +```json +{ + "$schema": "https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/v0/schema/agentconfigscore.schema.json", + "version": 1, + "policy": { + "max_drop": 0, + "fail_on_new_errors": true + } +} +``` + +比较时以**基线策略**为准：PR 不能通过放宽自己的阈值，或新增自己的豁免来批准自己。需要接受某项例外时，必须经过基线审核，填写规则 ID、原因和到期日期；被豁免的发现仍保留审计记录。 + +普通扫描默认只报告发现，不因发现问题就自动失败。需要绝对分数门槛时显式设置： + +```bash +agent-config-score . --fail-under 90 +``` + +## 本地检查与报告 + +```bash +agent-config-score . +agent-config-score rules curl-pipe-shell +agent-config-score diff origin/main +agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors +agent-config-score . --json +agent-config-score . --html .agent-config-score/report.html --sarif .agent-config-score/results.sarif +``` + +`diff` 包含未提交的工作区改动，自动基线检测不联网、不自动 fetch。找不到基线时，明确指定本地已有的默认分支引用。 + +规则、行号和上下文比数字本身更重要。报告可能包含仓库路径和发现信息，公开分享前请检查。`feedback` 可生成隐私最小化的本地草稿，但不会上传，仍需自己审核。 + +## 接入 GitHub Actions + +优先使用 `init` 生成工作流，也可以手工配置： + +```yaml +name: agent-config-regression + +on: + pull_request: + +permissions: + contents: read + +jobs: + regression: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + - uses: LE0-Lin/AgentConfigScore@v0.23.0 +``` + +固定 `@v0.23.0` 有利于复现；`@v0` 是会随后续版本更新的滚动引用。PR 评论属于[可选集成（英文）](docs/pr-comments.md)，扫描器默认不替你发评论。 + +## 支持的指令文件 + +包括根目录和嵌套目录的 `AGENTS.md` / `AGENTS.override.md`、`CLAUDE.md`、`GEMINI.md`、Cursor 的 `.cursorrules` / `.cursor/rules/`、Copilot 的 `.github/copilot-instructions.md` / `.github/instructions/`，以及 `.claude/`、`.clinerules`、`.windsurfrules`。可使用 `.agentconfigscoreignore` 排除发现路径。 + +准备自己的指令文件时，可参考[复制即用模板（英文）](examples/README.md)，并替换成仓库真正的命令和约束。不要为了得高分而复制空泛的“最佳实践”。 + +## 可靠性与边界 + +运行时没有第三方依赖；本地扫描不调用 AI API，也不执行指令文件中的命令。包安装需要访问所选软件包索引；GitHub Actions 是单独的 CI 环境，报告访问权限由你的工作流控制。 + +跨平台测试、维护的规则用例和安装验收证明程序符合指定的工程预期，**不证明它比直接问 AI 更准，也不证明它已经有真实用户价值**。独立对照评测尚未完成，已知语义漏报仍保留。详见[限制说明](docs/zh-CN/limitations.md)与[评测资料（英文）](benchmarks/README.md)。 + +本页是核心入门的中文概览，不是完整英文 README 的逐行翻译。使用指南和限制说明已提供中文；高级 Action 参数、规则语法细节、贡献及研究文档目前仍为英文。[翻译范围与维护说明](docs/translations.md)。命令、终端消息和 JSON 协议保持原样，English 仍是默认入口。 + +项目采用 [MIT 协议](LICENSE)。[发布与升级说明](docs/releases/v0.23.0.md)目前为英文。 diff --git a/README.zh-TW.md b/README.zh-TW.md new file mode 100644 index 0000000..98c6560 --- /dev/null +++ b/README.zh-TW.md @@ -0,0 +1,112 @@ +# AgentConfigScore + +[English](README.md) | [简体中文](README.zh-CN.md) | 繁體中文 + +為 AI 程式開發助手的指令檔提供本機檢查與 PR 回歸檢查。 + +![AgentConfigScore 示範](https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/main/assets/agent-config-score-demo.gif) + +AgentConfigScore 檢查 `AGENTS.md`、`CLAUDE.md`、Cursor、Copilot、Gemini 等設定，並與改動前的基準比較，回答一個具體問題：**這次改動是否引入了已知規則能偵測到的風險？** + +它是確定性的檢查工具，不是 AI 評審。**A 100 只表示沒有命中生效的規則，不代表指令實用、語意完美或完全安全。** 提供中文文件也不表示檢查工具已經能理解任意中文指令。 + +## 快速開始 + +需要 Python 3.10+。`diff` 另外需要 Git；一般目錄掃描和兩個目錄之間的 `compare` 不需要 Git。 + +```bash +python -m pip install --upgrade agent-config-score +agent-config-score --version +agent-config-score init +agent-config-score doctor +agent-config-score diff +``` + +請在自己的儲存庫目錄執行。`init` 會建立 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`；檢查並提交這兩個檔案後，後續 PR 即可自動檢查。它不會替你撰寫或改寫指令檔，也不會預設覆寫已存在且內容衝突的設定。 + +`acs` 是較短的命令別名。v0.23.0+ 也能使用 `python -m agent_config_score`，不必依賴終端機 PATH 找到主命令。 + +- [繁體中文使用指南](docs/zh-TW/user-guide.md)：安裝、基準、報告、結束代碼與疑難排解。 +- [分數意義與限制](docs/zh-TW/limitations.md)：先了解能偵測哪些問題，以及可能遺漏什麼。 +- [完整英文文件索引](docs/README.md)：進階介面與研究資料。 + +## 為什麼使用回歸檢查 + +既有儲存庫不必先達到 100 分才能導入。若基準為 72 分，沒有退步的改動可以通過；分數下降或引入新錯誤時，則依設定阻擋。 + +初始化後的核心策略如下： + +```json +{ + "$schema": "https://raw.githubusercontent.com/LE0-Lin/AgentConfigScore/v0/schema/agentconfigscore.schema.json", + "version": 1, + "policy": { + "max_drop": 0, + "fail_on_new_errors": true + } +} +``` + +比較以**基準策略**為準：PR 不能透過放寬自己的門檻，或新增自己的排除設定來核准自身。若需接受某項例外，必須經過基準審查，指定規則 ID、原因與到期日；被排除的檢查結果仍會保留稽核紀錄。 + +一般掃描預設只回報結果，不會只因發現問題就自動失敗。需要絕對分數門檻時，請明確設定： + +```bash +agent-config-score . --fail-under 90 +``` + +## 本機檢查與報告 + +```bash +agent-config-score . +agent-config-score rules curl-pipe-shell +agent-config-score diff origin/main +agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors +agent-config-score . --json +agent-config-score . --html .agent-config-score/report.html --sarif .agent-config-score/results.sarif +``` + +`diff` 包含尚未提交的工作目錄改動；自動偵測基準不連線，也不自動 fetch。找不到基準時，請明確指定本機已存在的預設分支參照。 + +規則、行號與上下文比數字本身更重要。報告可能包含儲存庫路徑和檢查資訊，公開分享前請先檢查。`feedback` 能產生盡量減少私人資訊的本機草稿，但不會上傳，仍須自行審閱。 + +## 整合 GitHub Actions + +建議用 `init` 產生工作流程，也可以手動設定： + +```yaml +name: agent-config-regression + +on: + pull_request: + +permissions: + contents: read + +jobs: + regression: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + - uses: LE0-Lin/AgentConfigScore@v0.23.0 +``` + +固定使用 `@v0.23.0` 較容易重現；`@v0` 是會隨後續版本更新的滾動參照。PR 留言是[選用整合（英文）](docs/pr-comments.md)，檢查工具預設不會替你留言。 + +## 支援的指令檔 + +包含根目錄與巢狀目錄的 `AGENTS.md` / `AGENTS.override.md`、`CLAUDE.md`、`GEMINI.md`、Cursor 的 `.cursorrules` / `.cursor/rules/`、Copilot 的 `.github/copilot-instructions.md` / `.github/instructions/`，以及 `.claude/`、`.clinerules`、`.windsurfrules`。可用 `.agentconfigscoreignore` 排除探索路徑。 + +準備自己的指令檔時，可參考[可直接複製的範本（英文）](examples/README.md)，再替換成儲存庫真正的命令與限制。不要為了提高分數而複製空泛的「最佳實務」。 + +## 可靠性與界線 + +執行時沒有第三方相依套件；本機掃描不呼叫 AI API，也不執行指令檔內的命令。安裝套件需存取選定的套件索引；GitHub Actions 是獨立的 CI 環境，報告存取權限由你的工作流程決定。 + +跨平台測試、持續維護的規則案例與安裝驗收，證明程式符合指定的工程預期，**不代表它比直接詢問 AI 更準確，也不代表已經具備真實使用者價值**。獨立對照評測尚未完成，已知的語意漏報仍保留。請見[限制說明](docs/zh-TW/limitations.md)與[評測資料（英文）](benchmarks/README.md)。 + +本頁是核心入門的中文概覽，不是完整英文 README 的逐行翻譯。使用指南與限制說明已提供中文；進階 Action 參數、規則語法細節、貢獻和研究文件目前仍為英文。[翻譯範圍與維護說明](docs/translations.md)。命令、終端機訊息和 JSON 協定維持原樣，English 仍為預設入口。 + +專案採用 [MIT 授權](LICENSE)。[發布與升級說明](docs/releases/v0.23.0.md)目前為英文。 diff --git a/docs/README.md b/docs/README.md index c9b2a35..391ac32 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # Documentation +[English](user-guide.md) | [简体中文](zh-CN/user-guide.md) | [繁體中文](zh-TW/user-guide.md) + Start with the [user guide](user-guide.md): install, initialize, check a change, read the result, and troubleshoot a failing gate. diff --git a/docs/limitations.md b/docs/limitations.md index 0ea6876..4c45744 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -1,5 +1,7 @@ # What the score does—and does not—mean +English | [简体中文](zh-CN/limitations.md) | [繁體中文](zh-TW/limitations.md) + AgentConfigScore is a deterministic linter and regression gate for persistent coding-agent instructions. Its score measures detected, rule-defined risks. It does not measure whether an AI agent is intelligent, whether a prompt will solve diff --git a/docs/release-readiness.md b/docs/release-readiness.md index 47c9cb5..92d3655 100644 --- a/docs/release-readiness.md +++ b/docs/release-readiness.md @@ -54,18 +54,18 @@ The release workflow is manual. Running tests or merging a readiness PR does not create a tag or publish to PyPI. This document is a gate definition, not an assertion that all future release steps have already been performed. -## Next milestone: optional Chinese documentation +## Optional Chinese documentation -After the core package is cut, add a lightweight language switch in each README: +After the v0.23.0 core package was cut, a documentation update adds a language switch in each README: English (default), 简体中文 and 繁體中文. The approach follows [Transformers' multilingual README](https://github.com/huggingface/transformers/blob/main/README.md) without adding a documentation framework or runtime translation dependency. -Planned files: +Initial core documentation: - `README.zh-CN.md` and `README.zh-TW.md`, with reciprocal language links. -- `docs/zh-CN/` and `docs/zh-TW/` versions of the user guide, limitations and - configuration / suppression guidance first; advanced reference pages follow. +- `docs/zh-CN/` and `docs/zh-TW/` versions of the user guide and limitations, + including the core policy / exception explanations; advanced references remain English. - A translation maintenance note recording the English source revision and explicitly identifying untranslated pages instead of linking empty placeholders. @@ -81,6 +81,8 @@ Rules for the translation stage: - Do not add a CLI `--language` option until terminal-output localization is explicitly in scope and independently tested. Documentation is the first stage. -The translated files and language selector are planned, **not shipped yet**. +The repository's core translated pages and selector are included in the +documentation update, not retroactively in the immutable v0.23.0 distributions +or tag. See [translation scope and source revision](translations.md). Real-user feedback and independent evaluation remain separate ongoing work; they are not replaced by localization or release acceptance. diff --git a/docs/translations.md b/docs/translations.md new file mode 100644 index 0000000..41689f1 --- /dev/null +++ b/docs/translations.md @@ -0,0 +1,41 @@ +# Optional documentation languages + +[English](../README.md) | [简体中文](../README.zh-CN.md) | [繁體中文](../README.zh-TW.md) + +English is the default repository entrypoint and package README. Choosing a +different document language does not change CLI output, rule grammar, scores, +configuration version, command names, JSON keys or API behavior. There is no +runtime `--language` option. Chinese instruction semantics are not certified by +providing Chinese documentation. + +## Available scope + +| English source | 简体中文 | 繁體中文 | Scope | +|---|---|---|---| +| [README](../README.md) | [Overview](../README.zh-CN.md) | [Overview](../README.zh-TW.md) | Localized core overview, not the entire long English reference | +| [User guide](user-guide.md) | [Guide](zh-CN/user-guide.md) | [Guide](zh-TW/user-guide.md) | Core user journey, all executable examples, exit codes and troubleshooting | +| [Limitations](limitations.md) | [Limits](zh-CN/limitations.md) | [Limits](zh-TW/limitations.md) | Core score contract, rule limits and unestablished accuracy; historic table/manual links stay in English | + +Advanced Action inputs/outputs, precise rule grammars, score-history integrations, +release notes, contribution instructions and research protocols remain English. +Localized pages identify those links as English instead of creating empty pages. +The two Chinese variants are maintained with Simplified and Traditional regional +wording rather than changing the program's machine-readable identifiers. + +## Source baseline and maintenance + +The first localized core pages use English source revision +`78af3f9a470c9edab67f3d1579e8319a299bb191` (v0.23.0). The repository language +links are a subsequent documentation update; they are not inside the immutable +v0.23.0 PyPI distributions or v0.23.0 tag. + +When an English source page changes, review both variants together and record +the new source revision here. Preserve executable examples, rule IDs and JSON +keys verbatim. Keep the score limitations and failure/exit semantics aligned; +do not translate a prohibition into an affirmative command. Mark any partial +coverage clearly and retain links to the English reference. + +Tests verify language-link targets, guide code-block parity, identical config +and workflow examples between variants, and English as the default package +README. They cannot verify translation meaning or serve as independent human +review. Wording and rule interpretation still need review when sources change. diff --git a/docs/user-guide.md b/docs/user-guide.md index e24f654..e9628c8 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,5 +1,7 @@ # User guide +English | [简体中文](zh-CN/user-guide.md) | [繁體中文](zh-TW/user-guide.md) + AgentConfigScore is a local, deterministic linter and pull-request regression gate for coding-agent instructions. It does not call an AI service or execute commands found in instruction files. A 100 means no active rule matched, not diff --git a/docs/zh-CN/limitations.md b/docs/zh-CN/limitations.md new file mode 100644 index 0000000..fa69f01 --- /dev/null +++ b/docs/zh-CN/limitations.md @@ -0,0 +1,63 @@ +# 分数含义与限制 + +[English](../limitations.md) | 简体中文 | [繁體中文](../zh-TW/limitations.md) · [使用指南](user-guide.md) + +AgentConfigScore 的分数衡量已经检测到的、由规则定义的风险，不衡量模型智力、任务成功率或指令总体质量。**A 100 表示没有命中生效的确定性规则，不是语义质量或安全认证。** + +## 高分不代表没有问题 + +只要避开已知规则，下列内容仍可能得到 100 分： + +- 空泛、无用但非空的指令。 +- 没有使用已知危险命令表达的恶意或有害意图。 +- 经过改写、措辞不完全相同的矛盾。 +- 不在规则目录中的破坏性工具、命令形式。 +- 语法正确但与实际仓库任务不匹配的指导。 + +我们不会用容易复制的“最佳实践”关键词加分来掩盖这些限制。模型辅助的语义判断需要独立评测和标注数据，不能通过更强的宣传措辞替代。 + +中文文档是可选阅读入口。**它不表示检测规则能理解任意简体或繁体中文语义。** 英文散文规则的跨语言表现尚未得到验证；中文的否定、例子、改写和矛盾仍需要人工审核。 + +## 命令与禁止上下文 + +`rm-rf`、`git-clean-force`、`docker-system-prune` 解析有限 shell 片段的选项，支持部分重排、拆分、长选项、引号内的选项值和显式反斜杠续行。shell 分隔符与 `--` 会停止选项解释。Git 的预览/交互模式排除在危险匹配外；`rm` 后出现的交互选项会覆盖强制模式。排除/过滤选项的值不会当成执行标志。 + +片段最多 1,000 个字符。普通操作数之后的选项、变量展开、别名、包装函数、子命令前的全局选项不解析。其他命令规则仍采用较窄的模式，不能覆盖所有 shell 语法。 + +明确识别的英文禁止语句可以覆盖紧邻且闭合的代码块，或连续的直接命令列表。这不是完整 Markdown 解析器或意图分类器：没有标签的代码仍会接受危险命令检查；未闭合代码块不继承禁止作用域；直接出现的凭据独立检查。引号或代码围栏本身也不是通用豁免。 + +复杂教学示例可能误报。先核对上下文，再使用有理由、有到期日期且经基线审核的豁免。[具体语法与负例（英文）](../instruction-context.md)。 + +## 提示注入与工作流规则 + +`prompt-injection-override` 识别 `ignore previous instructions` 等明确英文短语。命中只代表需要审核，不证明发生攻击。明确禁止以及整行标记的攻击示例可排除；任意改写、其他语言、运行时工具输出或远程内容的注入不在覆盖范围。[英文限制说明](../limitations.md#prompt-injection-warnings)。 + +`false-success-report` 要求完整的英文散文子句，明确隐瞒错误却报告成功，或在失败/未执行时声称测试通过。仅跳过测试、禁止性描述、引号或代码示例不足以满足该规则。它不跨句、跨行拼接证据，也不检查实际测试是否运行。其他有害指导仍可能通过。[规则细节（英文）](../verification-reporting.md)。 + +`broad-environment-upload` 要求同一英文子句同时包含明确传输行为、完整环境变量来源和网络接收端。仅变量名称、明确脱敏、日志、禁止描述、代码示例不满足此语法。它不读取进程环境、不验证脱敏、不解析目标，也不证明恶意意图或实际传输。字面回环地址被排除，但转发不分析；shell 上传、其他语言和任意改写仍不支持。[规则细节（英文）](../environment-upload.md)。 + +## 本地 Markdown 链接 + +简单的行内链接、图片目标相对于指令文件目录检查。URL 编码空格和尖括号目标受支持；只检查文件是否存在，不检查片段对应的标题。远程链接、纯锚点、代码块示例、绝对路径和逃出仓库的路径会跳过。引用式链接及目标中嵌套括号暂不解析，普通散文路径启发式保持原有行为。这不是完整 Markdown 校验器。 + +## 回归保护的具体范围 + +- 没有支持的指令文件会产生 `no-config`；空文件会产生 `empty-instructions`，不会显示 A 等级。 +- 生效的错误发现会限制等级，不能仅因数值惩罚较小就显示 A。 +- 精确指令形式的矛盾可以检出，改写后的语义矛盾不保证检出。 +- 删除指令文件会产生回归专用的 `instruction-file-removed`；内容完全相同的移动不作为删除。 +- 相同指令正文的明确极性翻转会产生 `directive-polarity-flip`，不推断任意语义相反的句子。 + +对应行为有回归测试，基线审核的豁免可记录有意接受的例外。通过测试只证明符合这些已指定的行为。 + +## 评测尚未证明什么 + +维护的离线对抗用例目前有 474/474 个确定性契约匹配；公开挑战中检出 6/8，仍保留两个语义漏报。这是封闭开发用例的回归结果，**不是现实仓库准确率**。修复已知的虚假成功报告和环境上传案例是开发进展，不是独立准确率估计。 + +与直接 AI 审查的独立对照尚未完成。比较工具包含已知的合成校准数据和暂定标签；未回答、未审核、未执行、参考标签未解决的情况，不会被当成完成的成功测量。一次未定论 AI 预评审、失败的源码获取，以及公共仓库片段，都不是已核验的用户反馈或优于 AI 的证据。[评测方法（英文）](../review-comparison.md)。 + +## 合适的用途 + +用于发现稳定规则覆盖的具体回归、在 CI 中审核发现、保留例外审计记录。不要作为生成代码、仓库安全或指令质量的唯一审批依据。安装验收、文档本地化和真实用户价值是不同问题。 + +本文根据英文限制说明整理，保留核心边界；历史版本的逐项对照表和外部手册引用请见[英文原文](../limitations.md)。[翻译范围与维护说明](../translations.md)。 diff --git a/docs/zh-CN/user-guide.md b/docs/zh-CN/user-guide.md new file mode 100644 index 0000000..360d335 --- /dev/null +++ b/docs/zh-CN/user-guide.md @@ -0,0 +1,115 @@ +# 使用指南 + +[English](../user-guide.md) | 简体中文 | [繁體中文](../zh-TW/user-guide.md) · [项目主页](../../README.zh-CN.md) + +AgentConfigScore 是本地、确定性的编程助手指令检查器和 PR 回归门禁。它不调用 AI 服务，也不执行指令文件中的命令。100 分不代表指令有用、始终安全或比 AI 审查更好。 + +## 1. 安装并确认版本 + +需要 Python 3.10+。`diff` 需要 Git；普通目录扫描和两个目录间的 `compare` 不需要 Git。 + +```bash +python -m pip install agent-config-score +agent-config-score --version +agent-config-score --help +``` + +`acs` 是短命令别名。v0.23.0+ 支持相同功能的 `python -m agent_config_score`，不依赖主命令的 PATH 设置。旧版本没有此模块入口。查看[已发布版本](https://github.com/LE0-Lin/AgentConfigScore/releases)，不要默认认为 `main` 的改动已经进入 PyPI 或滚动 `v0` 引用。 + +## 2. 在自己的仓库初始化 + +```bash +agent-config-score init --dry-run +agent-config-score init +agent-config-score doctor +``` + +`init` 生成 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`，不创建或改写指令文件。已有冲突文件默认不覆盖；使用 `--force` 前先检查。与生成内容相同的重复初始化不会改动文件。 + +审核后提交生成的配置和工作流。只想本地使用时选 `init --no-workflow`；标准工作流缺失会成为 doctor 的提示性警告，而不是错误。 + +若没有找到支持的指令文件，请编写符合仓库实际情况的指令，或采用[模板（英文）](../../examples/README.md)。不要仅为涨分添加词句。[完整发现范围（英文）](../../README.md#what-it-scans)。 + +## 3. 检查当前目录 + +```bash +agent-config-score . +agent-config-score rules +agent-config-score rules curl-pipe-shell +``` + +普通扫描默认报告发现，不因为有发现就自动阻止后续操作。需要绝对分数门槛时，在策略中设置 `fail_under` 或明确传入： + +```bash +agent-config-score . --fail-under 90 +``` + +仓库不必先达到 90 分才能采用回归门禁。请结合规则、位置、上下文审核结果，不要把分数当成总体质量排名。 + +## 4. 推送前检查改动 + +```bash +agent-config-score diff +``` + +包括未提交的工作区改动。尽可能采用本地已有的安全默认分支基线，不自动 fetch。也可明确指定： + +```bash +agent-config-score diff origin/main +``` + +如果引用不存在，请自己获取该分支。应选择项目真正的默认分支，而非已经包含改动的功能分支。浅克隆需要足够的历史；生成的 Actions 工作流使用 `fetch-depth: 0`。 + +没有 Git 时，可以比较两个已存在的目录： + +```bash +agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors +``` + +两侧均使用基线策略和豁免。候选改动不能通过提高自己的降分预算或豁免新错误来批准自己；可信调用方的命令行覆盖必须明确传入。 + +## 5. 理解失败并处理 + +- `diff` / `compare` 返回 `1`：配置的回归门禁未通过。检查新发现与允许的降分幅度，处理实际指令问题。 +- 疑似误报仍需审核。接受的例外可以使用经基线审核的豁免，填写稳定规则 ID、原因、到期日期；结果保留审计记录。[豁免细节（英文）](../../README.md#auditable-exceptions)。 +- 返回 `2`：检查无法完成，如配置无效、Git 引用缺失、报告不可写。**这不是干净的结果**，不能因为没有 JSON 就批准改动。 + +| 命令 | 返回 0 | 返回 1 | 返回 2 | +|---|---|---|---| +| 扫描（`agent-config-score .`） | 扫描完成，满足可选门槛 | 低于设置的分数门槛 | 输入无效或操作错误 | +| `diff`、`compare` | 基线策略通过 | 新错误或降分门禁未通过 | 无法完成比较 | +| `doctor` | 无错误项，可能有警告 | 有错误检查项 | 参数或调用错误 | +| 其他命令 | 请求的操作完成 | 不是 lint 门禁 | 输入无效或操作错误 | + +意外的程序错误不会被通用异常捕获隐藏。分享堆栈前先删除私密信息；回归测试通过并不保证程序没有 bug。 + +## 6. 在本地保存报告 + +```bash +agent-config-score . --json +agent-config-score . --html .agent-config-score/report.html --badge .agent-config-score/badge.svg --sarif .agent-config-score/results.sarif +agent-config-score diff --markdown .agent-config-score/regression.md +``` + +不要把报告放在会被当成指令文件扫描的位置。JSON、HTML、SARIF 和回归报告可能包含仓库路径及发现信息，分享前先检查。输出路径不要选成源码或策略文件，避免覆盖。多个报告写入不是事务：后一个写入失败时，前一个报告可能已生成。 + +需要隐私最小化草稿时： + +```bash +agent-config-score feedback . --output .agent-config-score/case.md +``` + +不会上传任何内容。请自行审核、脱敏后再分享。 + +## 常见问题 + +| 现象 | 检查方法 | +|---|---| +| 找不到命令 | 确认装入当前 Python 环境，并检查 Scripts/bin 的 PATH。v0.23.0+ 可用 `python -m agent_config_score`。 | +| 配置或工作流编码错误 | 保存为 UTF-8，不要用 UTF-16 文件替代。 | +| 报告不可写 | 选择可写的文件路径，不是已有目录；检查父目录权限。 | +| 无法检测基线 | 运行 `doctor`，然后指定本地已有的默认分支引用。 | +| 禁止示例被报为危险指令 | 对照[支持的禁止语法（英文）](../instruction-context.md)检查具体上下文；工具不理解任意语言和改写。 | +| 旧 GitHub 运行记录是红色 | 查看当前提交对应的运行。后续修复不会抹掉历史失败记录。 | + +使用前阅读[限制说明](limitations.md)。发现是审核信号，不代替代码审查或安全评估。[翻译范围](../translations.md)。 diff --git a/docs/zh-TW/limitations.md b/docs/zh-TW/limitations.md new file mode 100644 index 0000000..933e93f --- /dev/null +++ b/docs/zh-TW/limitations.md @@ -0,0 +1,63 @@ +# 分數意義與限制 + +[English](../limitations.md) | [简体中文](../zh-CN/limitations.md) | 繁體中文 · [使用指南](user-guide.md) + +AgentConfigScore 的分數衡量已偵測到、由規則定義的風險，不衡量模型智力、任務成功率或指令整體品質。**A 100 表示沒有命中生效的確定性規則，不是語意品質或安全認證。** + +## 高分不代表沒有問題 + +只要避開已知規則，下列內容仍可能得到 100 分： + +- 空泛、沒有實際用途但並非空白的指令。 +- 未透過已知危險命令表達的惡意或有害意圖。 +- 經過改寫、措辭不完全相同的矛盾。 +- 規則目錄以外的破壞性工具或命令形式。 +- 語法正確卻不符合實際儲存庫任務的指導。 + +我們不會藉由容易複製的「最佳實務」關鍵字加分來掩飾限制。模型輔助的語意判斷需要獨立評測與標註資料，不能用更強的宣傳措辭取代。 + +中文文件是選用的閱讀入口。**它不表示偵測規則能理解任意簡體或繁體中文語意。** 英文敘述規則的跨語言表現尚未驗證；中文的否定、範例、改寫與矛盾仍須人工審查。 + +## 命令與禁止上下文 + +`rm-rf`、`git-clean-force`、`docker-system-prune` 解析有限 shell 片段的選項，支援部分重新排序、拆分、長選項、引號內的選項值與明確反斜線續行。shell 分隔符號與 `--` 會停止解讀選項。Git 的預覽/互動模式排除於危險匹配之外；`rm` 後續的互動選項會覆蓋強制模式。排除/過濾選項的值不會被當作執行旗標。 + +片段最多 1,000 個字元。一般運算元之後的選項、變數展開、別名、包裝函式與子命令前的全域選項不解析。其他命令規則仍使用較窄的模式，無法涵蓋所有 shell 語法。 + +可明確識別的英文禁止語句，能涵蓋緊鄰且已閉合的程式碼區塊，或連續的直接命令清單。這不是完整 Markdown 解析器或意圖分類器：沒有標籤的程式碼仍接受危險命令檢查；未閉合區塊不繼承禁止範圍；直接出現的認證資訊會獨立檢查。引號或程式碼圍欄本身也不是通用豁免。 + +複雜的教學範例可能誤報。先核對上下文，再使用附有原因、到期日且經基準審查的排除設定。[具體語法與反例（英文）](../instruction-context.md)。 + +## 提示注入與工作流程規則 + +`prompt-injection-override` 識別 `ignore previous instructions` 等明確英文片語。命中只表示需要審查，不證明發生攻擊。明確禁止及整行標記的攻擊範例可排除；任意改寫、其他語言、執行時工具輸出或遠端內容的注入不在涵蓋範圍。[英文限制說明](../limitations.md#prompt-injection-warnings)。 + +`false-success-report` 要求完整英文敘述子句，明確隱瞞錯誤卻回報成功，或在失敗/未執行時宣稱測試通過。僅略過測試、禁止性描述、引號或程式碼範例不足以符合規則。它不跨句、跨行組合證據，也不檢查實際測試是否執行。其他有害指導仍可能通過。[規則細節（英文）](../verification-reporting.md)。 + +`broad-environment-upload` 要求同一英文子句同時包含明確傳輸行為、完整環境變數來源與網路接收端。只有變數名稱、明確移除敏感資訊、日誌、禁止描述或程式碼範例，不符合此語法。它不讀取處理程序環境、不驗證敏感資訊處理、不解析目標，也不證明惡意意圖或實際傳輸。字面回環位址排除在外，但不分析轉送；shell 上傳、其他語言和任意改寫仍不支援。[規則細節（英文）](../environment-upload.md)。 + +## 本機 Markdown 連結 + +簡單的行內連結、圖片目標依指令檔目錄檢查。支援 URL 編碼空格與尖括號目標；只檢查檔案是否存在，不檢查片段對應的標題。遠端連結、純錨點、程式碼區塊範例、絕對路徑與離開儲存庫的路徑會略過。參照式連結及目標中巢狀括號暫不解析，一般敘述路徑的啟發式維持原有行為。這不是完整 Markdown 驗證工具。 + +## 回歸保護的具體範圍 + +- 沒有支援的指令檔會產生 `no-config`；空白檔案會產生 `empty-instructions`，不會顯示 A 等級。 +- 生效的錯誤發現會限制等級，不會只因數值懲罰較小就顯示 A。 +- 可以偵測精確指令形式的矛盾，但不保證識別改寫後的語意矛盾。 +- 刪除指令檔會產生回歸專用的 `instruction-file-removed`；內容完全相同的搬移不視為刪除。 +- 相同指令正文的明確極性翻轉會產生 `directive-polarity-flip`，不推論任意語意相反的句子。 + +對應行為有回歸測試，基準審查的排除設定可記錄有意接受的例外。測試通過只證明符合這些已指定的行為。 + +## 評測尚未證明什麼 + +持續維護的離線對抗案例目前有 474/474 個確定性契約符合預期；公開挑戰中偵測到 6/8，仍保留兩個語意漏報。這是封閉開發案例的回歸結果，**不是實際儲存庫的準確率**。修正已知的虛假成功回報與環境上傳案例是開發進展，不是獨立準確率估計。 + +與直接 AI 審查的獨立對照尚未完成。比較工具包含已知的合成校準資料與暫定標籤；未回答、未審查、未執行、參考標籤尚未解決的情況，不會被視為已完成的成功測量。一次未定論 AI 預審、失敗的原始碼取得，以及公開儲存庫片段，都不是已驗證的使用者回饋或優於 AI 的證據。[評測方法（英文）](../review-comparison.md)。 + +## 合適的用途 + +用於發現穩定規則涵蓋的具體回歸、在 CI 中審閱發現，以及保留例外稽核紀錄。不要作為產生的程式碼、儲存庫安全或指令品質的唯一核准依據。安裝驗收、文件在地化與真實使用者價值是不同問題。 + +本文依英文限制說明整理，保留核心界線；歷史版本逐項比較表和外部手冊引用請見[英文原文](../limitations.md)。[翻譯範圍與維護說明](../translations.md)。 diff --git a/docs/zh-TW/user-guide.md b/docs/zh-TW/user-guide.md new file mode 100644 index 0000000..3e3528a --- /dev/null +++ b/docs/zh-TW/user-guide.md @@ -0,0 +1,115 @@ +# 使用指南 + +[English](../user-guide.md) | [简体中文](../zh-CN/user-guide.md) | 繁體中文 · [專案首頁](../../README.zh-TW.md) + +AgentConfigScore 是在本機執行、結果確定的開發助手指令檢查工具與 PR 回歸檢查。它不呼叫 AI 服務，也不執行指令檔內的命令。100 分不代表指令實用、始終安全或優於 AI 審查。 + +## 1. 安裝並確認版本 + +需要 Python 3.10+。`diff` 需要 Git；一般目錄掃描和兩個目錄之間的 `compare` 不需要 Git。 + +```bash +python -m pip install agent-config-score +agent-config-score --version +agent-config-score --help +``` + +`acs` 是較短的命令別名。v0.23.0+ 支援相同功能的 `python -m agent_config_score`，不依賴主命令的 PATH 設定。舊版本沒有此模組入口。請查看[已發布版本](https://github.com/LE0-Lin/AgentConfigScore/releases)，不要假設 `main` 的改動已經出現在 PyPI 或滾動 `v0` 參照。 + +## 2. 在自己的儲存庫初始化 + +```bash +agent-config-score init --dry-run +agent-config-score init +agent-config-score doctor +``` + +`init` 建立 `.agentconfigscore.json` 和 `.github/workflows/agent-config-score.yml`，不建立或改寫指令檔。既有衝突檔案預設不覆寫；使用 `--force` 前請先檢查。若內容與產生的設定相同，重複初始化不會改動檔案。 + +審閱後提交產生的設定與工作流程。只想在本機使用時選 `init --no-workflow`；缺少標準工作流程只會成為 doctor 的提示性警告，不是錯誤。 + +若沒有找到支援的指令檔，請撰寫符合儲存庫實際需求的指令，或使用[範本（英文）](../../examples/README.md)。不要只為提高分數添加詞句。[完整探索範圍（英文）](../../README.md#what-it-scans)。 + +## 3. 檢查目前目錄 + +```bash +agent-config-score . +agent-config-score rules +agent-config-score rules curl-pipe-shell +``` + +一般掃描預設回報結果，不會只因有發現就自動阻擋後續操作。需要絕對分數門檻時，在策略中設定 `fail_under` 或明確傳入： + +```bash +agent-config-score . --fail-under 90 +``` + +儲存庫不必先達到 90 分才能導入回歸檢查。請依規則、位置與上下文審閱結果，不要把分數當成整體品質排名。 + +## 4. 推送前檢查改動 + +```bash +agent-config-score diff +``` + +包含尚未提交的工作目錄改動。盡可能使用本機已存在的安全預設分支基準，不會自動 fetch。也能明確指定： + +```bash +agent-config-score diff origin/main +``` + +如果參照不存在，請自行取得該分支。應選專案真正的預設分支，而不是已經包含改動的功能分支。淺層複製需要足夠的歷史；產生的 Actions 工作流程使用 `fetch-depth: 0`。 + +沒有 Git 時，可以比較兩個已存在的目錄： + +```bash +agent-config-score compare ../repo-base . --max-drop 0 --fail-on-new-errors +``` + +兩側都套用基準策略與排除設定。候選改動不能藉由增加自己的降分預算或排除新錯誤來核准自身；受信任呼叫端若要覆寫命令列設定，必須明確傳入。 + +## 5. 理解失敗並處理 + +- `diff` / `compare` 返回 `1`：設定的回歸檢查未通過。檢查新增發現與允許的降分幅度，處理實際指令問題。 +- 疑似誤報仍須審閱。接受的例外可以使用經基準審查的排除設定，指定穩定規則 ID、原因與到期日；結果仍保留稽核紀錄。[例外細節（英文）](../../README.md#auditable-exceptions)。 +- 返回 `2`：檢查無法完成，例如設定無效、Git 參照不存在或報告無法寫入。**這不是乾淨的結果**，不能因為沒有 JSON 就核准改動。 + +| 命令 | 返回 0 | 返回 1 | 返回 2 | +|---|---|---|---| +| 掃描（`agent-config-score .`） | 掃描完成，符合選用門檻 | 低於設定的分數門檻 | 輸入無效或操作錯誤 | +| `diff`、`compare` | 基準策略通過 | 新錯誤或降分檢查未通過 | 無法完成比較 | +| `doctor` | 無錯誤項目，可能有警告 | 有錯誤檢查項目 | 參數或呼叫錯誤 | +| 其他命令 | 要求的操作完成 | 不是 lint 門檻檢查 | 輸入無效或操作錯誤 | + +非預期的程式錯誤不會被通用例外處理隱藏。分享堆疊資訊前請移除私人內容；回歸測試通過不保證程式沒有 bug。 + +## 6. 在本機儲存報告 + +```bash +agent-config-score . --json +agent-config-score . --html .agent-config-score/report.html --badge .agent-config-score/badge.svg --sarif .agent-config-score/results.sarif +agent-config-score diff --markdown .agent-config-score/regression.md +``` + +不要將報告放在會被視為指令檔掃描的位置。JSON、HTML、SARIF 與回歸報告可能包含儲存庫路徑和檢查資訊，分享前請先檢查。輸出路徑不要選擇原始碼或策略檔案，以免覆寫。多份報告寫入不是交易：後一份寫入失敗時，前一份可能已經產生。 + +需要盡量減少私人資訊的草稿時： + +```bash +agent-config-score feedback . --output .agent-config-score/case.md +``` + +不會上傳任何內容。請自行審閱並移除敏感資訊後再分享。 + +## 常見問題 + +| 現象 | 檢查方法 | +|---|---| +| 找不到命令 | 確認安裝在目前 Python 環境，並檢查 Scripts/bin 的 PATH。v0.23.0+ 可用 `python -m agent_config_score`。 | +| 設定或工作流程編碼錯誤 | 儲存為 UTF-8，不要以 UTF-16 檔案取代。 | +| 報告無法寫入 | 選擇可寫入的檔案路徑，不是既有目錄；檢查父目錄權限。 | +| 無法偵測基準 | 執行 `doctor`，再指定本機已存在的預設分支參照。 | +| 禁止範例被判為危險指令 | 對照[支援的禁止語法（英文）](../instruction-context.md)檢查上下文；工具不理解任意語言和改寫。 | +| 舊 GitHub 執行紀錄是紅色 | 查看目前提交對應的執行結果。後續修正不會抹除歷史失敗紀錄。 | + +使用前閱讀[限制說明](limitations.md)。發現是審查訊號，不代替程式碼審查或安全評估。[翻譯範圍](../translations.md)。 diff --git a/tests/test_documentation_languages.py b/tests/test_documentation_languages.py new file mode 100644 index 0000000..21788c3 --- /dev/null +++ b/tests/test_documentation_languages.py @@ -0,0 +1,88 @@ +import json +from pathlib import Path +import re +import unittest +from urllib.parse import unquote, urlsplit + +from agent_config_score.initializer import CONFIG_CONTENT + + +ROOT = Path(__file__).resolve().parents[1] +LOCALES = ("zh-CN", "zh-TW") + + +def blocks(text, language): + return re.findall(r"```" + re.escape(language) + r"\n(.*?)\n```", text, re.DOTALL) + + +class DocumentationLanguageTests(unittest.TestCase): + def test_english_stays_the_default_package_readme(self): + project = (ROOT / "pyproject.toml").read_text(encoding="utf-8") + self.assertIn('readme = "README.md"', project) + readme = (ROOT / "README.md").read_text(encoding="utf-8") + self.assertIn("English |", readme) + for locale in LOCALES: + self.assertIn(f"README.{locale}.md", readme) + page = (ROOT / f"README.{locale}.md").read_text(encoding="utf-8") + self.assertIn("[English](README.md)", page) + self.assertIn(f"docs/{locale}/user-guide.md", page) + self.assertIn(f"docs/{locale}/limitations.md", page) + + def test_localized_guides_preserve_every_english_executable_example(self): + source = (ROOT / "docs" / "user-guide.md").read_text(encoding="utf-8") + expected = blocks(source, "bash") + self.assertGreater(len(expected), 5) + for locale in LOCALES: + with self.subTest(locale=locale): + page = (ROOT / "docs" / locale / "user-guide.md").read_text(encoding="utf-8") + self.assertEqual(blocks(page, "bash"), expected) + for code in ("--max-drop", "--fail-on-new-errors", "--json", "--sarif", "--force"): + self.assertIn(code, page) + + def test_overviews_use_the_same_commands_config_and_workflow(self): + pages = [(ROOT / f"README.{locale}.md").read_text(encoding="utf-8") for locale in LOCALES] + for language in ("bash", "json", "yaml"): + with self.subTest(language=language): + self.assertEqual(blocks(pages[0], language), blocks(pages[1], language)) + self.assertTrue(blocks(pages[0], language)) + self.assertEqual(json.loads(blocks(pages[0], "json")[0]), json.loads(CONFIG_CONTENT)) + workflow = blocks(pages[0], "yaml")[0] + self.assertIn("contents: read", workflow) + self.assertIn("fetch-depth: 0", workflow) + self.assertIn("LE0-Lin/AgentConfigScore@v0.23.0", workflow) + + def test_localized_links_target_real_files_inside_the_repository(self): + paths = [ROOT / f"README.{locale}.md" for locale in LOCALES] + paths += [ROOT / "docs" / locale / name for locale in LOCALES + for name in ("user-guide.md", "limitations.md")] + paths += [ROOT / "docs" / "translations.md"] + for path in paths: + text = path.read_text(encoding="utf-8") + for destination in re.findall(r"!?\[[^\]\n]+\]\(([^)\n]+)\)", text): + parts = urlsplit(destination) + if parts.scheme or not parts.path: + continue + target = (path.parent / unquote(parts.path)).resolve() + with self.subTest(page=path.name, destination=destination): + self.assertTrue(target.is_relative_to(ROOT)) + self.assertTrue(target.is_file(), target) + + def test_core_limits_keep_stable_rule_ids_and_source_scope_visible(self): + for locale in LOCALES: + page = (ROOT / "docs" / locale / "limitations.md").read_text(encoding="utf-8") + for code in ("rm-rf", "prompt-injection-override", "false-success-report", + "broad-environment-upload", "no-config", "empty-instructions", + "instruction-file-removed", "directive-polarity-flip"): + self.assertIn(code, page) + self.assertIn("A 100", page) + self.assertIn("474/474", page) + self.assertIn("6/8", page) + self.assertIn("../translations.md", page) + note = (ROOT / "docs" / "translations.md").read_text(encoding="utf-8") + self.assertIn("78af3f9a470c9edab67f3d1579e8319a299bb191", note) + self.assertIn("cannot verify translation meaning", note) + self.assertIn("Advanced Action inputs/outputs", note) + + +if __name__ == "__main__": + unittest.main()