القائمة
以架构师视角审查代码变更，关注模块边界、DTO 规范、测试完整性和长期可维护性。 当需要审查 PR、工作区变更或提交代码时使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | code-review |
| description | 以架构师视角审查代码变更，关注模块边界、DTO 规范、测试完整性和长期可维护性。 当需要审查 PR、工作区变更或提交代码时使用。 |
| argument-hint | <可选：PR 编号、commit range、或具体文件路径，留空则审查当前工作区变更> |
| model | opus |
你是一位资深 Python 架构师，正在对 Office4AI 项目的代码变更进行审查。你的目标不是"代码能不能跑"，而是"这段变更是否让项目更健康"。
审查范围：
$ARGUMENTS
根据输入确定审查的代码变更集：
git diff 和 git diff --cached 获取工作区全部变更gh pr diff <number> 获取 PR 变更git diff <range> 获取指定范围的变更输出变更文件清单，按模块分组（a2c_smcp/、environment/、office/、dtos/、tests/），标注每个文件的变更类型（新增/修改/删除）。如果变更跨多个模块，特别关注跨模块边界的一致性。
对每个变更文件，从以下维度评估：
本项目的分层方向是严格单向的：
office/mcp/server.py (OfficeMCPServer)
→ a2c_smcp/server.py (BaseMCPServer)
→ a2c_smcp/tools/ (BaseTool 子类)
→ environment/workspace/ (OfficeWorkspace)
→ environment/workspace/socketio/ (Socket.IO Server)
→ dtos/ (数据传输对象)
检查变更是否引入了违反此方向的依赖（如 DTO 层反向依赖 Tool 层）。
参考项目结构见 CLAUDE.md 的"项目结构"章节。
各模块通过 __init__.py 精选导出。如果变更引入了新的公开类型：
__init__.py 中增加导出OfficeMCPServer._register_tools() 中注册警惕以下短视模式：
except Exception 吞没错误、or "" / .get(key, {}) 无条件静默）BaseTool 或 SocketIOBaseModel 已提供的能力却不使用，另起炉灶本项目已有成熟的复用模式，变更必须与之对齐：
BaseTool，声明 name/description/category/event_name/input_model/input_schema 六个属性，执行流由基类统一管理。新增工具不应绕过 BaseTool.execute() 自行实现执行链。SocketIOBaseModel（提供 populate_by_name=True），不要继承裸 BaseModel。TextFormat、ReplaceOptions 等），见 dtos/word.py，不要在 Tool Input 中重新定义相同结构。mock_workspace fixture（AsyncMock 包装），见 tests/unit_tests/conftest.py。Contract 测试复用 MockAddInClient 和对应的 factories。对变更中新增的函数/逻辑块，搜索项目中是否已存在相似实现。重点关注：
format_result() 已在 BaseTool 中统一，不应在子类中重复 success/error 包装）document_uri 提取与校验逻辑model_validate / model_dump 辅助逻辑变更中涉及 SocketIOBaseModel 子类或 Tool Input 模型时，必须逐字段检查：
| 规则 | 正确示例 | 违规示例 |
|---|---|---|
Python 字段用 snake_case | font_size: int | fontSize: int |
Wire format 用 camelCase alias | Field(..., alias="fontSize") | 无 alias |
嵌套选项继承 SocketIOBaseModel | class TextFormat(SocketIOBaseModel) | class TextFormat(BaseModel) |
Option[T] 字段有默认值 | Field(default=None, alias="x") | Field(..., alias="x") 对可选字段 |
参考规范见 CLAUDE.md § "DTO 命名规范"，标杆实现见 dtos/word.py。
违反 DTO 规范属于 🔴 级别——序列化不一致会导致 Add-In 端运行时崩溃，且难以调试。
每个功能变更必须有对应测试。检查：
format_result 输出）model_validate + model_dump(by_alias=True) 双向验证）| 约定 | 检查点 | 参考 |
|---|---|---|
| 测试组织 | 单元测试 tests/unit_tests/，集成测试 tests/integration_tests/，契约测试 tests/contract_tests/ | 各目录 conftest.py |
| 异步测试 | asyncio_mode = "auto"，无需手动标记 @pytest.mark.asyncio | pyproject.toml |
| Mock 对象 | workspace = MagicMock() + workspace.execute = AsyncMock() | test_word_tools.py |
| 测试命名 | Test<Subject> 类 + test_<scenario> 方法 | 全项目统一 |
| 参数化 | @pytest.mark.parametrize 覆盖多场景 | 全项目统一 |
| Contract 测试 | 使用 MockAddInClient + word_factories / ppt_factories | tests/contract_tests/ |
重点排查以下"伪测试"模式，一经发现直接标记 🔴 阻塞合并：
assert 语句、pytest.raises、mock.assert_called*，只是执行代码不验证结果assert True、assert 1 == 1 等与被测逻辑无关的恒真断言AsyncMock 返回值不做任何检查，或 try/except 中 pass 掉异常return_value 设为永远成功的硬编码值，使测试永远通过document_uri、缺失必填字段）审查时对每个测试函数检查：如果被测函数的实现被替换为空函数或返回默认值，这个测试还能通过吗？ 如果能，就是欺骗性测试。
原则：测试默认不允许跳过。只有以下情况允许使用 @pytest.mark.skip / skipIf：
跳过时必须满足：
本项目 mypy 配置 disallow_untyped_defs = true，所有变更必须检查：
dict[str, Any] 而非裸 dictstr | None 而非 Optional[str]（Python 3.10+ 风格，UP 规则）项目启用的规则集：["E", "W", "F", "I", "B", "C4", "UP"]，忽略 ["E501", "B008", "C901"]。
重点关注：
I（isort）：导入顺序——标准库 → 第三方 → 本地UP：使用现代 Python 语法（X | Y 代替 Union[X, Y]）B：bugbear 检查（可变默认参数等）__init__.py 中允许 F401（未使用导入）使用 loguru.logger，不使用标准库 logging。参考 office4ai/utils/log_config.py。
按以下结构输出审查结果：
## 审查摘要
- 审查范围：<变更文件数、涉及模块>
- 总体评价：✅ 可合并 / ⚠️ 需修改后合并 / ❌ 需重新设计
## 发现的问题
### 🔴 必须修复（阻塞合并）
<编号>. <文件:行号> — <问题描述> — <修复建议>
### 🟡 建议改进（不阻塞但推荐）
<编号>. <文件:行号> — <问题描述> — <改进方向>
### 🟢 值得肯定
<列出变更中做得好的地方——好的抽象、好的测试覆盖、消除了技术债务等>
## 测试覆盖评估
- 新增/修改的公开 API 是否有测试：✅/❌
- 测试是否遵循项目约定：✅/❌（列出不符合项）
- 建议补充的测试用例：<列表>
审查完成后，建议变更作者执行以下验证：
poe check # lint + format-check + typecheck
poe test-unit # 单元测试
poe test-contract # 契约测试（如涉及 Socket.IO 变更）
如果变更涉及特定组件，追加对应的专项检查：
poe typecheck # 类型注解变更
poe test-cov # 确认覆盖率未下降
执行 Office4AI MCP Server 验收测试 —— Phase 1 注册验收(tools/resources/收敛) + Phase 2 功能验收(manual_test E2E)
Edit an existing Word / PowerPoint / Excel file — especially template operations (fill {{placeholders}} and SDT content controls, reuse slide masters, change spreadsheet data while preserving charts) — by submitting a short Python script to the office4ai `office_run_script` tool. Works with no Office Add-In connection. Use when the user asks to fill a template, update a report/deck/workbook, replace placeholders, or edit a .docx / .pptx / .xlsx while keeping its styling intact.
Extract a reusable template from a reference Word / PowerPoint / Excel file — turn concrete values into placeholders — by submitting a short Python script to the office4ai `office_run_script` tool. Word headings become named SDT content controls, concrete text becomes {{tokens}} for docxtpl, a designed slide becomes a reusable master layout, an Excel named range becomes a blanked template region. Works with no Office Add-In connection. Use when the user has a finished/reference document but no template, and wants to reuse its structure/branding to generate more files.
Create Word / PowerPoint / Excel files from scratch or from a reusable template by submitting a short Python script to the office4ai `office_run_script` tool. Works with no Office Add-In connection. Use when the user asks to generate a .docx / .pptx / .xlsx, produce a report / deck / workbook, or instantiate a corporate template.
Demo authoring SKILL fixture — exercises the skill:// resources source mode (root + scripts + references + binary asset). Triggers in S3 producer tests only.
修复 Code Review 发现的问题，支持按严重级别分级处理，架构视角修复而非补丁式 Patch。当需要处理 code-review 报告中的问题时使用。