| name | tablecodeagent-dev-prompt |
| description | 为 TableCodeAgent 仓库生成可直接交给 Codex/Agent 执行的中文项目化开发 prompt。用户要求使用 $tablecodeagent-dev-prompt，或要求为 TableCodeAgent 的普通代码实现、修复治理、benchmark、trace、validation、runner、表格工具、Agent 工具注册、文档同步、skill/指令文件维护任务生成执行 prompt 时使用；Plan Mode prompt 改用 $tablecodeagent-plan-mode-prompt，代码评审 prompt 改用 $tablecodeagent-code-review-prompt。本 skill 只产出任务 prompt，不直接开始执行开发任务。 |
TableCodeAgent 开发 Prompt
技能定位
生成一次具体 TableCodeAgent 开发、修复、治理或文档同步任务的执行 prompt。它的唯一主产物是一份能复制给 Codex/Agent 立刻执行的中文项目化开发 prompt，不是变量表、教程、结构规范、通用模板说明，也不是直接开始执行 prompt 中的开发任务。
Plan Mode prompt 交给 $tablecodeagent-plan-mode-prompt。代码评审 prompt 交给 $tablecodeagent-code-review-prompt。如果一次开发 prompt 的执行依赖外部最新知识、官方 API、论文、benchmark、Agent 框架、LLM API 或工程实践，最终 prompt 可以要求后续执行者调用 $web-search，并把外部结论转成当前仓库可验证的工程约束、测试和证据。
技能交叉引用规则
如果生成的 prompt 需要明确要求后续执行者调用其他 skill，必须使用 $skill-name 形式，例如 $web-search。不要只写反引号包裹的 skill 名称，也不要把 skill 路由写成普通文件路径。
只有在说明源码位置、必读文件或验证证据时，才写 .agents/skills/<skill-name>/... 文件路径。
使用流程
- 先确认用户要的是“生成开发执行 prompt”，不是直接执行修复、直接进入 Plan Mode 或直接做代码评审。
- 读取当前仓库规则和任务相关材料，默认至少包括
.codex/AGENTS.md、README.md、docs/reproduce/tablecodeagent_architecture.md、docs/reproduce/why_table_code_agent.md，以及本轮涉及的真实调用链、task、脚本、文档或 skill 文件。
- 读取
references/prompt-template.md 作为底稿，只保留本轮适用段落，不保留空占位符、旧路径或模板说明。
- 从用户输入和仓库材料中提取：
- 仓库路径，默认要求执行者以“当前仓库”为准并现场核对。
- 任务类型：普通代码实现、修复治理、benchmark / trace / validation / runner、表格工具、Agent 工具注册、文档同步、skill / 指令文件维护。
- 问题背景、目标现象、强制边界、禁止修改范围和必做 TODO。
- 必读文件、真实入口、真实调用链、真实测试入口和证据路径要求。
- 版本、README、架构文档、修复报告和真实 API /
SKIP 边界。
- 按本轮任务删减和填充底稿，生成一个完整、连续、可复制、可执行的中文 prompt。
- 输出前将生成的 prompt 保存为临时草稿或放入可检查文件，并运行本 skill 的专项校验脚本：
python -X utf8 .agents/skills/tablecodeagent-dev-prompt/scripts/validate_tablecodeagent_dev_prompt.py <prompt_path>
- 如果脚本失败，必须根据缺失项补齐 prompt 并复跑，直到通过；如果仍有无法验证边界，必须在最终回答中明确写出剩余不可验证项。该脚本只检查关键结构和质量约束是否保留，不判断具体任务内容是否已经完全覆盖用户意图。
- 输出最终 prompt。代码块前最多一句中文引导，代码块后不要追加正文。
默认补全规则
- 仓库路径：优先使用用户给出的路径；没有明确路径时写“当前仓库”，并要求执行者先核对真实工作目录。
- 语言：全程简体中文；代码、命令、报错原文、文件路径、API 字段名、模型名、库名、域名和专有名词保留英文原文。
- 修改策略：默认最小必要改动，先读入口、调用链、工具注册、数据路径和验证方式，再改代码；但“最小”必须服从业务口径、工程分层、可验证闭环和评测可信度，不能为了少改几行保留错误 benchmark 口径、弱 JSON 契约、helper 暴露或失败归因缺口。
- 路径核对：要求执行者用
rg --files 或等价命令刷新当前仓库真实路径，不沿用历史报告里的旧入口、旧脚本或旧目录。
- 版本策略：用户未明确要求升版时，沿用当前仓库版本，不主动 bump；只有核心代码、可执行能力、工具协议、benchmark / trace / validation / runner 等实质变化才评估版本号与修复报告。
- 文档与报告：纯文档、skill、指令文件、格式、注释类调整不触发修复报告或版本号变更；核心行为变化才按
.codex/AGENTS.md 规则处理。
- 修复报告内容质量：生成开发 prompt 时，如果本轮可能触发
docs/reproduce/fix-report-*.md，必须要求后续执行者写入报告可读性规范。报告不能只堆路径、英文术语或字段名；涉及 benchmark、trace、answer.json、Pydantic schema、task output_contract、no-helper、SKIP、failure_type 等概念时，要补中文含义和对 TableCodeAgent 评测结论的影响说明。
- 多次验证结构：如果后续执行者进行了多次真实 API 评测、代码 smoke、simulated Agent / mocked Agent 回归或重复验证，prompt 必须要求报告用平行的三级标题区分每一次测试，并在每次测试下用四级标题解释现象、原因和修复后变化；最后先用平行的三级标题建立汇总区，例如
### 真实 API 多轮汇总 或 ### 多轮测试汇总，再在其下用 #### 总表 和 #### 归因总结 汇总多次测试，不能直接孤立写四级汇总标题，也不能只按时间顺序堆日志。
- API 与密钥：禁止修改或提交
configs/api/local/、.env、真实 API key；需要真实 API 验证时只允许读取用户指定 env 文件，若用户未指定 env，则默认使用 configs/api/local/deepseek.env；env 缺失、网络失败、依赖缺失或模型行为不可控时记录 SKIP 或“未验证”，不能伪装成功。
- 外部实践：涉及 Agent benchmark、structured output、JSON Schema / Pydantic、tool schema、风控 / 营销 / 定价等工业业务流程，或当前仓库规则与外部规范可能冲突时，prompt 中可以要求执行者调用
$web-search；用户明确要求不联网时不要写入联网要求。
- TODO 分块：TODO 多时按
A / B / C / D 分块；单任务只保留一个任务块，不堆空标题。
- 不编造事实：当前版本、已实现能力、最近验证结果、文件存在性和 API 状态必须要求执行者从仓库或本轮命令刷新确认。
Prompt 固定结构
除非用户明确要求极短版，最终 prompt 按下面顺序组织：
- 任务开场：明确仓库、目标和“不允许跳过”的执行口吻。
【硬性前置要求（必须先做）】【项目定位与边界】【版本、文档与报告策略】【本次要完成的 TODO，必须全部落地】【实现约束】【测试与验证要求，必须执行】【交付物要求】【注意】
不适用的空段落要删除或合并，不要保留空标题、无用变量或模板说明。
输出包裹规则
- 最终 prompt 必须整体放入单个 Markdown 文本块，方便用户一次性复制。
- 如果 prompt 内部包含三反引号，外层使用四反引号或更长围栏，例如 ````text。
- 不要用 XML / HTML 标签、引用块、普通列表或多个代码块替代单个文本块。
- 输出代码块前最多写一句中文引导，例如“下面是可直接执行的 prompt。”
- 输出代码块后不要追加正文，避免影响复制。
TableCodeAgent 专项护栏
生成 prompt 时必须保留这些项目约束：
- TableCodeAgent 是面向复杂表格任务的轻量级 Coding Agent 项目，不是普通数据分析 Agent，也不要包装成 SFT、RL、RAG、Memory 增强或 SOTA 项目。
- 当前工程主线是复用
mini_claude baseline，逐步加入表格工具、任务转换、执行验证、轨迹记录、benchmark 和失败分析。
- 新增能力优先放在
src/tablecodeagent/ 领域模块，再通过轻量 adapter 接入 mini_claude Agent Runtime；不要把核心计算、数据清洗、trace、benchmark、validation、runner 逻辑堆进 src/mini_claude/tools.py。
- 单个模块只承载一个清晰职责；大函数要拆成可命名、可单测、可复用的小函数。
- 错误处理必须可观测，不吞异常伪装成功；校验失败不能包装成“无数据”或“已通过”。
- Agent 输出 JSON、
answer.json、tool input / output schema 和 task output_contract 必须是机器可校验契约，不能只靠“请输出 JSON”或顶层 key 列表；复杂场景优先使用 JSON Schema、Pydantic model 或同等方案。
- 真实 LLM Agent benchmark 必须采用 no-helper 口径。prompt 必须禁止把
implementation_hints、allowed_project_helpers、solve_py_suggestion、完整 workflow import 路径或 build_*_report() 这类解题入口公开给模型；如果需要验证项目内 helper，只能作为 unit / integration / smoke / regression 测试，不能命名为 benchmark，不能计入模型能力结论。
- benchmark、trace、runner、validation 改动必须区分非 API 模式和真实 LLM 模式；非 API 通过不能写成真实 LLM Agent 行为已验证。
- 不新增无依据的固定超时、轮次上限、重试上限、prompt / 工具输出 / CSV / trace 截断、静默降级或隐藏兜底。
- 不把未实现能力、未验证能力、
SKIP 场景或推测写成已完成、已通过或事实。
- 不提交
configs/api/local/、.env、真实 API key、__pycache__、.pyc 或无关生成文件。
任务类型专项规则
表格工具 / 数据读取 / 查询
- 要求先阅读
src/tablecodeagent/table_tools/、src/tablecodeagent/agent_tools.py、相关 benchmark task 与 smoke 脚本。
- TODO 必须覆盖数据口径、输入格式、失败方式、错误可观测性和最小测试样例。
- 测试至少要求跑表格工具 smoke；涉及 Excel、多表、multi-header、merged cell 时加入对应任务验证。
- 禁止为了通过 demo 伪造 schema、伪造统计、伪造答案或跳过异常。
Agent 工具注册 / tool schema / Runtime 分发
- 要求先阅读
src/mini_claude/tools.py、src/mini_claude/agent.py、src/tablecodeagent/agent_tools.py 和相关脚本。
- 必须验证模型可见 tool schema，以及
mini_claude.tools.execute_tool() 本地分发能返回可读结果。
- 不允许只改 schema 不接执行路径，也不允许只接执行路径但模型不可见。
benchmark / runner / trace / validation
- 要求明确 runner 模式、输入任务目录、输出
results.jsonl、trace 路径、失败类型与指标口径。
- 要求真实 benchmark 采用 no-helper 口径，只允许给模型 task、数据文件、允许的通用库、公开输出契约和必要环境约束。
- 要求检查并移除会泄露解题入口的
implementation_hints、allowed_project_helpers、solve_py_suggestion；如果历史 task 仍保留这些字段，prompt 必须要求执行者先迁移为 no-helper task，再运行真实 benchmark。
- 要求
output_contract 与 pytest / validator 真实读取路径对齐，至少覆盖顶层 key、关键嵌套路径、字段类型和结构错误分类。不得把 schema_check.passed=true 等同于最终通过。
- 真实 LLM 验证必须记录
api_called、skipped、llm_tool_call_observed、tool_call_count、validation.passed、failure_type 等关键字段。
- 如果 env 缺失、网络失败、模型未调用工具或权限不足，必须如实写
SKIP 或未验证原因。
文档 / README / 架构记录
- 要求先读
.codex/AGENTS.md 的文档目录、修复报告和版本规则。
- README 面向项目总览，
docs/reproduce/ 面向开发证据和可复现记录，docs/baseline/ 保留 baseline 教程型文档。
- 不要把历史状态写成最新状态；涉及“当前支持什么”必须从代码、脚本和最近验证结果确认。
- 纯文档调整默认不触发修复报告和版本号变更，最终 prompt 中要要求说明原因。
- 如果本轮触发修复报告，最终 prompt 必须要求报告解释得通俗可读：技术术语、字段名、文件路径和测试结果要配中文解释；真实 API、smoke、simulated Agent 等多次验证要用清晰标题分组，并先用平行三级标题建立多轮汇总区，再在下面用总表和归因总结说明每次测试证明了什么、失败原因是什么、哪些仍未验证。
skill / 指令文件维护
- 明确这是维护 Codex/Agent 指令资产，不是修改 TableCodeAgent 核心运行能力。
- 要求检查 skill 的存放目录、frontmatter、references 文件和可调用性边界；只有当前仓库真实存在
agents/openai.yaml 时才要求检查该文件。
- 默认不要求跑 TableCodeAgent smoke tests；验证重点是文件存在、UTF-8 可读、YAML / frontmatter 关键字段存在、
references/ 引用路径真实存在、脚本语法、校验脚本结果和无旧项目私有残留。
- 项目本地
.agents/skills/<skill-name> 不等于当前会话或其他会话一定自动发现；如果用户要求全局 $skill-name 可调用，必须另行同步到当前 Codex 实际发现的全局 skill 目录，本 skill 不默认执行全局同步。
- 最终总结必须说明本轮是否触发版本号、README、架构文档或修复报告；默认不触发时说明原因。
计划模式
- 不在本 skill 中生成 Plan Mode prompt。
- 用户要求 Plan Mode、只读探索、先提炼关键决策点、先让用户拍板时，改用
$tablecodeagent-plan-mode-prompt。
代码评审
- 不在本 skill 中生成代码评审 prompt。
- 用户要求 code review、审查 prompt、findings first 或默认不修复的审查任务时，改用
$tablecodeagent-code-review-prompt。
质量标准
- 最终 prompt 要像执行指令，不像建议、教程或泛泛计划。
- 约束必须具体、可检查、可落地。
- 交付物必须明确到文件改动、验证命令、证据路径、风险与未验证项。
- 不触发版本、README、架构文档或修复报告时，prompt 必须要求执行者在最终总结中说明原因。
- 不要机械复制其他项目的私有路径、版本号、测试命令、报告规则或发布流程。
- 不要为了显得完整堆空壳、堆模板、堆不可验证约束。
自检
输出 prompt 前逐条检查：
- 是否明确本轮只是生成 prompt，不是已经执行开发任务。
- 是否没有输出变量清单、可复用模板、结构规范或教程。
- 是否已读取并遵守
.codex/AGENTS.md 和本轮真实仓库材料。
- 是否写入 TableCodeAgent 的项目定位，而不是泛化成普通数据分析 Agent。
- 是否要求先读
.codex/AGENTS.md、README.md 和相关真实调用链。
- 是否避免硬编码过期版本、过期支持状态或不存在的文件。
- 是否明确版本、文档和修复报告策略。
- 是否针对任务类型加入 smoke、benchmark、trace、LLM/API、YAML/frontmatter、脚本语法或校验脚本验证要求。
- 是否明确哪些场景必须写“未验证”或
SKIP，而不是伪装成功。
- 是否保留 no-helper benchmark、tool schema、
output_contract、LLM/API 与密钥安全边界。
- 如果 prompt 中交叉引用其他 skill，是否统一使用
$skill-name 形式。
- 是否已运行
validate_tablecodeagent_dev_prompt.py，并根据失败项循环修改到通过或说明不可验证边界。
- 最终 prompt 是否完整放在一个 Markdown 文本块中；如果内部含 ```，外层围栏是否使用 ````text 或更长围栏。
- 如果本轮是 Plan Mode 或代码评审 prompt，是否已路由到独立 skill，而不是在本 skill 里继续生成。
