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.

2026-07-152

extract-template

A2C-SMCP/office4ai

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.

2026-07-152

create-office-file

A2C-SMCP/office4ai

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.

2026-07-102

demo-authoring

A2C-SMCP/office4ai

Demo authoring SKILL fixture — exercises the skill:// resources source mode (root + scripts + references + binary asset). Triggers in S3 producer tests only.

2026-07-092

code-review

A2C-SMCP/office4ai

以架构师视角审查代码变更，关注模块边界、DTO 规范、测试完整性和长期可维护性。当需要审查 PR、工作区变更或提交代码时使用。

2026-03-102

name	fix-review
description	修复 Code Review 发现的问题，支持按严重级别分级处理，架构视角修复而非补丁式 Patch。当需要处理 code-review 报告中的问题时使用。
argument-hint	<block\|all\|discuss> [报告来源]
model	opus

Fix Review / Code Review 问题修复命令

你是一位资深 Python 架构师，正在处理 Office4AI 项目的 Code Review 报告。你的修复不是简单的 Patch，而是从全局架构出发，先验证问题真实性，再制定系统性修复方案。

输入

原始参数：$ARGUMENTS

Step 0: 解析参数

对 $ARGUMENTS 按以下规则解析：

第一个空格前的 token 为修复模式
剩余部分为报告来源（可选）

修复模式

参数	修复范围	说明
`block`	仅 BLOCK 问题（🔴）	必须修复的阻塞合并问题
`all`	BLOCK + WARN 问题（🔴 + 🟡）	阻塞问题 + 建议改进项
`discuss`	INFO / 架构讨论项	以 interview 模式讨论方案，不直接改代码
留空/其他	等同 `block`	默认仅修复阻塞问题

报告来源

格式	示例	说明
`#PR-<number>`	`#PR-123`	从 GitHub PR review comments 获取报告
`@<文件路径>`	`@reports/review.md`	从指定文件读取报告内容
自然语言	`上次对话的报告`	在对话上下文中查找匹配的报告
留空		默认从当前对话上下文查找

用法示例：

/fix-review block                      # 修复当前对话报告中的 BLOCK 问题
/fix-review all #PR-123                # 从 PR #123 获取报告，修复 BLOCK + WARN
/fix-review discuss @review-report.md  # 读取文件报告，讨论 INFO 项

Step 1: 定位审查报告

根据报告来源定位：
- #PR-<number>：使用 gh api repos/{owner}/{repo}/pulls/<number>/comments 获取 PR review comments
- @<文件路径>：直接读取指定文件
- 自然语言 / 留空：查看当前对话上下文中的 Code Review 报告输出
- 如果以上均未找到，使用 git log --oneline -20 查看最近提交，尝试推断审查范围
- 如果仍无法定位，请求用户提供 Code Review 报告内容
解析报告结构：

报告通常包含：
- 🔴 必须修复（阻塞合并）：编号 1.、2. ...，含 文件:行号 — 问题描述 — 修复建议
- 🟡 建议改进（不阻塞但推荐）：同上
- 🟢 值得肯定：无需处理
- 测试覆盖评估：可能包含需要补充的测试用例建议
提取每个问题的：编号、文件路径、问题描述、建议方案。
根据修复模式筛选目标问题集合。

Step 2: 验证问题真实性（对每一个问题必做）

核心原则：Code Review 可能误判，修复不存在的问题比不修复真实问题更危险。

2.1 读取原始代码

读取报告中指出的文件和行号的完整上下文（至少前后 30 行）
对于跨模块问题，追踪完整调用链（DTO → Service → Namespace → Tool）

2.2 验证清单

对每个问题逐项核实：

问题代码是否存在？ — 报告指向的代码行是否真实存在（可能已被其他改动修复）
问题描述是否准确？ — 代码的实际行为是否真如报告所述
问题是否有真实影响？ — 是否会导致 bug、类型错误、性能退化、维护困难等实际后果
建议方案是否合理？ — Review 给出的修复建议是否是最优方案，还是有更好的全局方案

2.3 验证结论分类

结论	说明	后续行动
✅ 确认存在	问题真实存在，影响明确	进入 Step 3 修复
⚠️ 部分成立	问题存在但严重程度或范围与报告不符	修正后进入 Step 3
❌ 误判	问题不存在或描述不准确	跳过，在报告中说明
🔄 已修复	问题曾经存在但已被其他改动修复	跳过，在报告中确认

输出验证摘要（每个问题一行）：

[🔴1] DTO 字段缺少 alias → ✅ 确认存在 — dtos/word.py:142 确实缺少 camelCase alias
[🔴2] 未处理的异常 → ❌ 误判 — 上游 try/except 已覆盖此路径
[🟡1] 重复逻辑 → ⚠️ 部分成立 — 确有重复但涉及历史实现，需评估修改范围

等待用户确认验证结论后再继续。

Step 3: 设计修复策略（针对确认的问题）

禁止逐个问题打补丁，必须先建立全局修复视图。

3.1 问题归类与关联分析

同文件问题合并：同一文件的多个问题在一次修改中统一解决
同层级问题归组：按项目分层归组（DTO → Resources → Tools → Server）
因果关系识别：某些问题可能是其他问题的症状
修改顺序规划：先底层（dtos/、schema.py）→ 再中间层（resources/、tools/）→ 最后上层（server.py、tests/）

3.2 方案设计原则

根因修复：不做 patch，直接修正问题根源
最小侵入：修复不引入新的架构债务
全局一致：搜索类似场景的既有实现作为参考（如 DTO 规范参照 dtos/word.py）
副作用评估：列出修改可能影响的其他模块和测试
协议兼容：涉及 DTO 或 Socket.IO 事件的修改需对照 OASP 协议定义确认兼容性

3.3 输出修复计划

## 修复计划

### Group 1: DTO 层修正（影响: dtos/）
- [🔴1] 补全 alias — 统一检查同文件所有字段的 camelCase alias
- 关联影响: 依赖此 DTO 的 Tool input_model 需同步验证

### Group 2: Resource 层修正（影响: a2c_smcp/resources/）
- [🟡1] 消除重复逻辑 → 提取共用方法到基类
- 关联影响: 单元测试需同步更新

修改文件清单:
1. office4ai/dtos/word.py — alias 补全
2. office4ai/a2c_smcp/resources/window.py — 消除重复
3. tests/unit_tests/... — 补充测试

等待用户确认修复计划后再执行。

Step 4: 执行修复

按修复计划逐组执行：

4.1 修改前检查

读取待修改文件的完整内容（不能只看 diff，要理解全貌）
搜索项目中的类似实现作为风格参考
确认没有遗漏的关联引用（Grep 搜索 import / 调用处）

4.2 修改执行规范

遵循 CLAUDE.md 中的项目约定：

DTO 修改：snake_case 字段 + camelCase alias，嵌套模型继承 SocketIOBaseModel
类型注解：所有函数必须有类型注解（mypy disallow_untyped_defs = true）
行长度：120 字符
导入顺序：标准库 → 第三方 → 本地（ruff 自动管理）
测试补充：遵循 test_<subject>_<scenario> 命名，pytest 标记正确

4.3 修改后立即验证

每组修改完成后：

poe format                # 格式化
poe lint                  # Lint 检查
poe typecheck             # 类型检查

如果修改了特定模块，追加对应测试：

poe test-unit             # 单元测试
poe test-integration      # 集成测试（如涉及 Socket.IO / MCP 层）
poe test                  # 全量测试（最终确认）

Step 5: 讨论模式（仅 discuss 模式）

当参数为 discuss 时，不执行代码修改，而是进入 interview 模式：

逐条讨论每个 INFO / 架构讨论项：
- 解释问题的技术背景和架构影响
- 提出 2-3 个可选方案，分析各自的 trade-off

讨论框架（对每个讨论项）：

### 讨论：xxx

**背景**：[为什么这是一个值得讨论的架构决策]

**方案 A**：[描述] — 优势：... 劣势：...
**方案 B**：[描述] — 优势：... 劣势：...

**我的建议**：[基于项目现状推荐的方案及理由]

→ 你的看法？

讨论达成共识后：
- 如果需要修改代码，按 Step 3-4 执行
- 如果决定暂不修改，记录决策理由
- 如果涉及协议层变更，需对照 OASP 协议定义确认兼容性

Step 6: 输出修复总结

# Fix Review Summary / 问题修复总结

## 验证结果

| 编号 | 问题           | 验证结论    |
| ---- | -------------- | ----------- |
| 🔴1  | DTO alias 缺失 | ✅ 已修复   |
| 🔴2  | 未处理异常     | ❌ 误判跳过 |
| 🟡1  | 重复逻辑       | ✅ 已修复   |

## 修改文件清单

| 文件                                | 修改类型   | 关联问题 |
| ----------------------------------- | ---------- | -------- |
| office4ai/dtos/word.py              | alias 补全 | 🔴1      |
| office4ai/a2c_smcp/resources/...    | 消除重复   | 🟡1      |

## 验证状态

- [ ] `poe format` 通过
- [ ] `poe lint` 通过
- [ ] `poe typecheck` 通过
- [ ] 涉及模块的单元测试通过
- [ ] `poe test` 全量通过

## 备注

- [误判问题的说明]
- [涉及协议层的兼容性确认]
- [遗留的讨论项]

反模式（严格禁止）

不验证就修复：不确认问题是否真实存在就动手改代码
逐个打补丁：不做全局分析，头痛医头脚痛医脚
为修复而修复：问题不存在也硬改一些东西交差
引入新问题：修复过程中引入新的类型错误、硬编码、分层违规
忽略关联影响：改了 DTO 不更新下游 Tool / Test 的引用
跳过验证步骤：改完不运行 lint / typecheck / test
在 discuss 模式直接改代码：讨论项需要共识，不能擅自决定
违反 DTO 命名规范：直接使用 camelCase 字段名而非 snake_case + alias