From 0e5a17fe888223c27f3b1331c884decfcae29c63 Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Wed, 2 Sep 2026 15:26:23 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=8D=87=E7=BA=A7=20DevHarness=20?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF=E5=88=B0=2040b9938=20(#1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 同步上游两个提交，均为通用 Agent 工作规则： - 90938be #31 语言与术语：默认中文协作，标识符、命令、路径、API 名、 日志与错误原文保持原样不翻译 - 40b9938 #28 Windows PowerShell 命令约束：禁止套用 Bash heredoc 与 转义规则，正则引号处理，here-string 传多行 Python，rg 用 -g/--glob AGENTS.md 以上游新版重建，逐字保留本项目第 10 节「项目专用规则」。 dev_scripts/ 与 tests/ 本项目未定制，整体替换为上游版本。 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01LbdtsD3ohhSMy3KPoCgARq --- AGENTS.md | 11 +++++++++++ dev_scripts/harness.py | 11 +++++++++++ tests/test_harness_docs.py | 26 ++++++++++++++++++++++++++ 3 files changed, 48 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 512a089..89b694c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,12 @@ [项目档案](docs/00-project-profile.md) 按需阅读，不作为每次任务的固定前置。首次接手项目、治理模式不清楚，或出现下列情况之一时必须读：需要环境、配置或凭据来源；需要确认目录边界；需要判断子项目与交付单元划分；需要 DevHarness 来源与基线；需要项目专用验收要求。同一会话已经确认且没有变化时不重复读取；只为查命令不必打开项目档案。 +## 语言与术语 + +- 用户可以使用中文、英文或合理的中英混合语言交流；默认使用中文分析、回复、编写工单和维护内部项目文档。 +- 代码标识符、命令、参数、路径、文件名、API 名称、协议名、日志和错误原文保持原样；合理的英文术语可以保留，必要时首次出现补充简短中文解释。 +- 用户明确要求某次回复或交付物使用其他语言时，按该次要求执行；不得为了语言统一改写事实、接口契约或影响搜索和执行的原文。 + ## 常用命令 所有命令默认从仓库根目录执行，与项目档案保持一致。 @@ -175,6 +181,11 @@ - 优先运行项目档案中记录的格式检查、静态检查、单元测试和必要的集成测试。 - 不能验证的真机、生产、迁移或并发行为必须写入工单；存在明确要求的任务快照时再同步记录。 - Windows 环境优先使用当前已配置的 PowerShell；可选择时优先 PowerShell 7 `pwsh.exe`，不得仅为设置编码重复启动一层 PowerShell。 +- Windows 命令不得默认套用 Bash 的 heredoc、变量、路径、引号或转义语法；只有明确调用 Bash、WSL 或 Git Bash，并确认路径与编码边界时才使用。 +- PowerShell 中不需要变量展开的正则优先使用单引号；复杂正则优先使用变量或 `rg -e`，不得为了避开转义而改变查询语义或堆叠重复搜索。 +- 多行 Python 使用单引号 PowerShell here-string 管道给 `python -`；起始标记后立即换行，结束标记单独占一行，不使用 Bash heredoc。 +- `foreach`、`if` 等语句块的输出进入管道前使用 `$()`、`@()` 或变量；普通命令输出直接进入管道。 +- `rg` 使用真实目录配合 `-g/--glob` 筛选路径；只有确实需要实体路径列表时才用 `Get-ChildItem` 展开并传递 `.FullName`。 - 文本文件读写在命令支持时显式指定 UTF-8；文件解码和控制台输出分别处理，只有出现真实乱码或已知宿主非 UTF-8 时才设置当前进程的输出编码或 Python UTF-8 环境变量。 - 不得默认使用 `-ExecutionPolicy Bypass`；只有可信 `.ps1`确实被执行策略阻止且没有更小替代方案时，才对该次进程使用并在工单记录原因。 diff --git a/dev_scripts/harness.py b/dev_scripts/harness.py index cdbf27d..dc8a7b8 100644 --- a/dev_scripts/harness.py +++ b/dev_scripts/harness.py @@ -77,6 +77,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "## 环境、配置与凭据", ), "docs/01-workflow.md": ( + "## 语言与术语", "## Gitea 交互与工单最小读取", "## 新项目 Wiki 初始化门禁", "## 按治理模式选择最小门禁", @@ -110,6 +111,7 @@ CORE_DOCUMENT_REQUIREMENTS = { "docs/04-local-development-and-verification.md": ( "## 环境要求", "## Windows PowerShell 与 UTF-8", + "### PowerShell 语法与外部命令", "## 第一次运行", "## 常用调试方式", "## 完成修改前", @@ -348,11 +350,20 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "不得把模板自带的本地 `docs/` 当作新项目 Wiki 已初始化的证据", "提交只包含当前任务相关文件", "不得仅为设置编码重复启动一层 PowerShell", + "不得默认套用 Bash", + "复杂正则优先使用变量或 `rg -e`", + "单引号 PowerShell here-string", + "`foreach`、`if` 等语句块", + "使用真实目录配合 `-g/--glob`", "文件解码和控制台输出分别处理", "不得默认使用 `-ExecutionPolicy Bypass`", "### 按治理模式选择最小设计证据", "轻量模式的小 Bug、局部样式或布局", "明确为虚构的测试数据无需形式化脱敏", + "用户可以使用中文、英文或合理的中英混合语言交流", + "默认使用中文分析、回复、编写工单和维护内部项目文档", + "日志和错误原文保持原样", + "按该次要求执行", "完整独立需求、新页面、重大交互或导航变化", "`prototypes/<工单号>/<版本>/index.html`", "默认直接通过 Quant-UX 或其他设计工具的线上链接审核", diff --git a/tests/test_harness_docs.py b/tests/test_harness_docs.py index cdf9efb..dbae729 100644 --- a/tests/test_harness_docs.py +++ b/tests/test_harness_docs.py @@ -108,6 +108,16 @@ class CoreDocumentTests(unittest.TestCase): check_agent_efficiency_rules(errors) self.assertEqual(errors, []) + def test_agents_and_workflow_share_language_policy(self) -> None: + agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8") + workflow = (ROOT / "docs/01-workflow.md").read_text(encoding="utf-8") + for text in (agents, workflow): + self.assertIn("中文", text) + self.assertIn("英文", text) + self.assertIn("默认使用中文", text) + self.assertIn("错误原文保持原样", text) + self.assertIn("按该次", text) + def test_existing_project_adoption_requires_upgrade_process(self) -> None: required = CORE_DOCUMENT_REQUIREMENTS[ "docs/08-existing-project-adoption.md" @@ -158,6 +168,22 @@ class CoreDocumentTests(unittest.TestCase): check_agent_efficiency_rules(errors) self.assertEqual(errors, []) + def test_windows_shell_rules_avoid_bash_and_ripgrep_traps(self) -> None: + agents = (ROOT / "AGENTS.md").read_text(encoding="utf-8") + profile = (ROOT / "docs/00-project-profile.md").read_text(encoding="utf-8") + local = ( + ROOT / "docs/04-local-development-and-verification.md" + ).read_text(encoding="utf-8") + self.assertIn("Windows 10", profile) + self.assertIn("PowerShell 7 `pwsh`", profile) + self.assertIn("不得默认套用 Bash", agents) + self.assertIn("复杂正则优先使用变量或 `rg -e`", agents) + self.assertIn("@'\nprint", local) + self.assertIn("@(foreach", local) + self.assertIn("rg -n -g '*.md'", local) + self.assertNotIn("通配目录必须先用 `Get-ChildItem -Filter`", local) + self.assertNotIn("正则本身同时包含单引号和双引号，优先拆成多个", local) + def test_deployment_template_is_required_and_mapped(self) -> None: path = "docs/templates/deployment.md" self.assertIn(path, REQUIRED_FILES)