Codex不好用？来看看你的配置是否有问题！！！Codex 示例配置（config.toml）
- 内容介绍
- 文章标签
- 相关推荐
「CC被A社限制使用，Codex逐渐发力，代码之巅，新王加冕」
最近Anthropic小动作挺多，比如说：
- 2.1.15版本开始逐渐弃用 npm 的安装方式
- claude code 一些暗配置在云上，方便Anthropic云控
- Anthropic明牌抵制大陆公司，大陆IP使用
- 接下来，好像还有一些小动作，这些信号告诉我们，需要备用方案
# Codex 示例配置（config.toml）V1.0
# 作者：大帅笔
# https://linux.do/u/dwifbytslqh/summary
# 核心模型选择
# Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。
# 支持 gpt-5.2-codex, gpt-5.2, o1-pro-codex 等
model = "gpt-5.2-codex"
# /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。
# 可设置为不同的模型以优化代码审查效果
review_model = "gpt-5.2-codex"
# 从 [model_providers] 中选择的提供方 id。默认："openai"。
# 可选值：openai, azure, ollama 等，需在 [model_providers] 部分定义
model_provider = "openai"
# 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。
# 设置为 ollama 等支持开源模型的提供方
# oss_provider = "ollama"
# 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。
# 取消注释以强制指定这些值。
# 模型的上下文窗口大小（token 数），影响单次请求可处理的最大代码量
# model_context_window = 128000 # token 数；默认：按模型自动决定
# 自动触发历史压缩的 token 阈值，0 表示使用模型默认值
# model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值
# 每个工具输出存储的最大 token 数，防止工具输出占用过多上下文
# tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
# 推理与详细度（支持 Responses API 的模型）
# 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh）
# 更高的推理强度会让模型思考更充分，但响应时间更长
model_reasoning_effort = "medium"
# 推理摘要：auto | concise | detailed | none（默认：auto）
# 控制是否显示模型的推理过程摘要
model_reasoning_summary = "auto"
# GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium）
# 影响模型回复的详细程度
model_verbosity = "medium"
# 为当前模型强制启用推理摘要（默认：false）
# 即使模型默认不支持，也尝试启用推理摘要
model_supports_reasoning_summaries = false
# 指令覆盖
# 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。
# 用于添加全局自定义指令，优先级高于 AGENTS.md
# developer_instructions = ""
#（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。
# 此选项已弃用，建议使用 AGENTS.md 文件
# instructions = ""
# 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。
# 自定义历史压缩的提示词，影响会话历史如何被压缩
# compact_prompt = ""
# 用文件路径覆盖内置的基础指令。默认：未设置。
# 从外部文件加载自定义指令
# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# 从文件加载历史压缩提示词覆盖。默认：未设置。
# 从外部文件加载自定义压缩提示词
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
# 通知
# 外部通知程序（argv 数组）。未设置时：禁用。
# 配置系统通知，例如使用 notify-send 在 Linux 上显示桌面通知
# 示例：notify = ["notify-send", "Codex"]
notify = [ ]
# 审批与沙箱
# 何时请求命令审批：
# - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认
# - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权
# - on-request：由模型决定何时询问（默认）
# - never：从不询问（风险较大）
approval_policy = "on-request"
# 工具调用的文件系统/网络沙箱策略：
# - read-only（默认）：只允许读取文件，最安全
# - workspace-write：允许在工作区写入文件
# - danger-full-access（无沙箱；极其危险）：允许任意文件操作和网络访问
sandbox_mode = "read-only"
# 认证与登录
# CLI 登录凭据的持久化方式：file（默认） | keyring | auto
# file：保存在文件中；keyring：使用系统密钥环；auto：自动选择
cli_auth_credentials_store = "file"
# ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认：
# 用于 ChatGPT 网页登录的端点
chatgpt_base_url = "https://chatgpt.com/backend-api/ "
# 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。
# 用于企业/团队账号的 workspace 隔离
# forced_chatgpt_workspace_id = ""
# 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。
# 可选值：chatgpt | api
# forced_login_method = "chatgpt"
# MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring
# 控制 MCP 服务器的 OAuth 令牌存储位置
mcp_oauth_credentials_store = "auto"
# 项目文档控制
# 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768
# 限制 AGENTS.md 文件的大小，防止占用过多上下文
project_doc_max_bytes = 32768
# 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[]
# 例如：[".codex", "PROJECT.md"]，会在找不到 AGENTS.md 时尝试这些文件
project_doc_fallback_filenames = []
# 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"]
# 当向上遍历目录树时，遇到这些文件/文件夹就认为是项目根
# project_root_markers = [".git"]
# 历史与文件打开方式
# 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none
# 控制 Codex 生成的文件链接如何在编辑器中打开
file_opener = "vscode"
# UI、通知与杂项
# 抑制内部推理事件的输出。默认：false
# 设置为 true 可隐藏模型的推理过程
hide_agent_reasoning = false
# 当可用时显示原始推理内容。默认：false
# 显示模型未格式化的原始推理文本
show_raw_agent_reasoning = false
# 禁用 TUI 中的"突发粘贴（burst-paste）"检测。默认：false
# 当快速粘贴大量内容时，Codex 会检测并提示确认，此选项可禁用该功能
disable_paste_burst = false
# 记录 Windows 入门设置确认（仅 Windows）。默认：false
# 标记 WSL 设置向导是否已确认
windows_wsl_setup_acknowledged = false
# 启动时检查更新。默认：true
# 控制 Codex 启动时是否检查新版本
check_for_update_on_startup = true
####
# Profiles（命名预设）
# 当前启用的 profile 名称。未设置时，不应用任何 profile。
# 可设置为 [profiles] 部分定义的预设名称，如 "default"
# profile = "default"
# Skills（按技能覆盖）
# 在不删除技能的情况下禁用或重新启用某个技能。
[[skills.config]]
# 技能文件的路径
# path = "/path/to/skill"
# 是否启用该技能，false 可临时禁用而不删除配置
# enabled = false
# 实验性开关（旧版；优先使用 [features]）
# 使用统一执行工具代替单独的命令工具（实验性）
experimental_use_unified_exec_tool = false
# 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false
# 允许更灵活的补丁应用方式
experimental_use_freeform_apply_patch = false
# 沙箱设置（表）
# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。
[sandbox_workspace_write]
# 除工作区（cwd）外额外允许写入的根目录。默认：[]
# 可添加多个受信任的写入目录
writable_roots = []
# 允许在沙箱内进行出站网络访问。默认：false
# 启用后，工具可以访问网络资源，有安全风险
network_access = false
# 将 $TMPDIR 从可写根目录中排除。默认：false
# 防止临时目录被意外写入
exclude_tmpdir_env_var = false
# 将 /tmp 从可写根目录中排除。默认：false
exclude_slash_tmp = false
# 生成子进程的 Shell 环境策略（表）
[shell_environment_policy]
# inherit：all（默认） | core | none
# 控制子进程继承哪些环境变量
inherit = "all"
# 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true
# 设置为 false 会更严格地清理敏感环境变量
ignore_default_excludes = true
# 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[]
# 可添加自定义的敏感变量模式
exclude = []
# 显式 key/value 覆盖（始终优先）。默认：{}
# 强制设置特定的环境变量
set = {}
# 白名单；若非空，则只保留匹配的变量。默认：[]
# 只保留匹配这些模式的变量
include_only = []
# 实验性：通过用户 shell profile 运行。默认：false
# 是否加载用户的 shell 配置文件（如 .bashrc, .zshrc）
experimental_use_profile = false
# 历史（表）
[history]
# save-all（默认） | none
# 控制是否保存命令历史
persistence = "save-all"
# 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880 (5MB)
# 限制历史文件大小，防止无限增长
# max_bytes = 0
# UI、通知与杂项（表）
[tui]
# 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true
# 可设置为 false 禁用通知，或指定特定事件类型
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 启用欢迎/状态/加载动画。默认：true
# 控制是否显示 TUI 动画效果
animations = true
# 在欢迎界面显示入门提示。默认：true
# 新用户引导提示
show_tooltips = true
# 可选的 TUI2 滚动调优（未设置则使用默认值）。
# 滚动灵敏度设置（高级用户）
# scroll_events_per_tick = 0
# scroll_wheel_lines = 0
# scroll_trackpad_lines = 0
# scroll_trackpad_accel_events = 0
# scroll_trackpad_accel_max = 0
# scroll_mode = "auto" # auto | wheel | trackpad
# scroll_wheel_tick_detect_max_ms = 0
# scroll_wheel_like_max_duration_ms = 0
# scroll_invert = false
# 控制用户是否可以通过 `/feedback` 提交反馈。默认：true
[feedback]
enabled = true
# 产品内提示（多由 Codex 自动设置）。
[notice]
# 隐藏完整访问权限警告
# hide_full_access_warning = true
# 隐藏全局可写警告
# hide_world_writable_warning = true
# 隐藏速率限制模型提示
# hide_rate_limit_model_nudge = true
# 隐藏 GPT 5.1 迁移提示
# hide_gpt5_1_migration_prompt = true
# 隐藏 GPT-5.1-codex-max 迁移提示
# "hide_gpt-5.1-codex-max_migration_prompt" = true
# 模型迁移映射，旧模型 -> 新模型
# model_migrations = { "gpt-4.1" = "gpt-5.1" }
# 集中式功能开关（推荐）
[features]
# 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。
# 启用 Shell 工具，允许执行命令
shell_tool = true
# 启用网页搜索请求功能
web_search_request = false
# 启用统一执行工具（实验性）
unified_exec = false
# 启用 Shell 快照功能
shell_snapshot = false
# 启用自由格式补丁应用（实验性）
apply_patch_freeform = false
# 启用执行策略功能
exec_policy = true
# 启用实验性 Windows 沙箱
experimental_windows_sandbox = false
# 启用需要管理员权限的 Windows 沙箱
elevated_windows_sandbox = false
# 启用远程压缩
remote_compaction = true
# 启用远程模型
remote_models = false
# 为 PowerShell 启用 UTF-8 编码支持
powershell_utf8 = true
# 启用 TUI2 界面（实验性）
tui2 = false
# 在此表下定义 MCP 服务器。留空则禁用。
[mcp_servers]
# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]
# enabled = true # 可选；默认 true
# command = "docs-server" # 必填：启动服务器的命令
# args = ["--port", "4000"] # 可选：命令行参数
# env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value
# env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量
# cwd = "/path/to/server" # 可选：工作目录覆盖
# startup_timeout_sec = 10.0 # 可选；默认 10.0 秒，启动超时
# # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名
# tool_timeout_sec = 60.0 # 可选；默认 60.0 秒，工具调用超时
# enabled_tools = ["search", "summarize"] # 可选：允许列表，只启用指定工具
# disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效）
# --- 示例：可流式 HTTP 传输 ---
# [mcp_servers.github]
# enabled = true # 可选；默认 true
# url = "https://github-mcp.example.com/mcp " # 必填：MCP 服务器 URL
# bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" } # 可选：静态请求头
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头
# startup_timeout_sec = 10.0 # 可选
# tool_timeout_sec = 60.0 # 可选
# enabled_tools = ["list_issues"] # 可选：允许列表
# 模型提供方（扩展/覆盖内置）
# 内置包括：
# - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY）
# - oss（Chat Completions API；默认指向 http://localhost:11434/v1）
[model_providers]
# --- 示例：用显式 base URL 或 headers 覆盖 OpenAI ---
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1 " # 未设置时的默认值
# wire_api = "responses" # "responses" | "chat"（默认因情况而异）
# # requires_openai_auth = true # 内置 OpenAI 默认 true
# # request_max_retries = 4 # 默认 4；最大 100
# # stream_max_retries = 5 # 默认 5；最大 100
# # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟）
# # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure（根据端点选择 Chat/Responses）---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai "
# wire_api = "responses" # 或按端点使用 "chat"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY"
# --- 示例：本地 OSS（例如 Ollama 兼容）---
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"
# Profiles（命名预设）
[profiles]
# 定义配置文件预设，可快速切换不同配置组合
# [profiles.default]
# model = "gpt-5.2-codex"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# oss_provider = "ollama"
# model_reasoning_effort = "medium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/ "
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_unified_exec_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# features = { unified_exec = false }
# Projects（信任级别）
# 将特定 worktree 标记为可信或不可信。
# 为不同项目设置不同的信任级别
[projects]
# 项目路径设置示例
# [projects."/absolute/path/to/project"]
# trust_level = "trusted" # 或 "untrusted"
# OpenTelemetry（OTEL）- 默认禁用
# 可观测性配置，用于监控和调试
[otel]
# 在日志中包含用户提示文本。默认：false（出于隐私考虑）
log_user_prompt = false
# 应用于遥测数据的环境标签。默认："dev"
environment = "dev"
# 导出器：none（默认） | otlp-http | otlp-grpc
# 设置为 none 则禁用遥测导出
exporter = "none"
# Trace 导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"
# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs " # OTLP 接收端点
# protocol = "binary" # "binary" | "json"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}" # 从环境变量读取 API 密钥
# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317 "
# headers = { "x-otlp-meta" = "abc123" }
# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs "
# protocol = "binary"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem" # CA 证书路径
# client-certificate = "/etc/codex/certs/client.pem" # 客户端证书
# client-private-key = "/etc/codex/certs/client-key.pem" # 客户端私钥
config.toml.txt (20.8 KB)
工具推荐
cometix/codex --by:哈雷
GitHub - Haleclipse/codex: Lightweight coding agent that runs in your...
Lightweight coding agent that runs in your terminal
# 卸载原版 Codex 相关组件（如有）
npm uninstall -g @openai/codex
# 安装哈雷版Codex（推荐）
npm install -g @cometix/codex --registry https://registry.npmjs.org
# 验证安装
codex --version
MCP推荐：
windows版：
# Chrome开发者工具
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60000
# Context7向量搜索
[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
startup_timeout_ms = 20000
# Replicate AI模型
[mcp_servers.replicate]
command = "cmd"
args = ["/c", "npx", "-y", "replicate-flux-mcp"]
env = {
SystemRoot="C:\\Windows",
PROGRAMFILES="C:\\Program Files",
REPLICATE_API_TOKEN="YOUR_TOKEN"
}
# GitHub Copilot
[mcp_servers.github]
command = "cmd"
args = [
"/c", "npx", "-y", "mcp-remote@latest",
"https://api.githubcopilot.com/mcp/",
"--header", "Authorization: Bearer YOUR_TOKEN"
]
MacOS版：
# 浏览器开发者工具
[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
# 时序思维助手
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
# 自动化测试工具
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# 时间管理
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
# 任务管理器
[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = {
DATA_DIR = "~/tools/mcp-shrimp-task-manager/data",
TEMPLATES_USE = "zh",
ENABLE_GUI = "false"
}
# 深度维基搜索
[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]
# 桌面控制
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
Skills
Codex-cli操控Gemini-cli的skills:
collaborating-with-gemini-cli-main.zip (14.7 KB)
Codex-cli操控Claude-code的skills
collaborating-with-claude-code-main.zip (15.9 KB)
openspec的skills
---
name: openspec
description: OpenSpec 中文版规范助手 - 规范驱动的 AI 编程开发，帮助初始化、创建提案、编写规格、校验格式并归档变更。触发条件： 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用。
trigger: 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用
---
# OpenSpec 中文版规范助手
OpenSpec 是一个 CLI 工具，通过**规范驱动的开发流程**帮助开发者与 AI 编码助手建立明确的需求共识。核心理念是：**在编写代码前，先将需求文档化并达成一致**，从而消除 AI 工具仅依赖对话历史产生的不可预测输出。
## 什么是 OpenSpec
### 核心价值
- **准确性**：需求明确后大幅减少返工，避免 AI 理解偏差
- **可追溯性**：每个技术决策都有完整的文档记录
- **文档化**：自动生成的规范与代码保持同步，形成活文档
- **团队友好**：清晰的提案便于多人协作和 Code Review
### 适用场景
✅ **最适合**：
- 改进现有项目（1→n 开发，棕地项目）
- 需要高质量实现的关键功能
- 团队协作开发
- 使用 Claude Code、Cursor、Cline 等 AI 工具
- 需要长期维护的项目
❌ **不适合**：
- 快速原型验证（0→1 探索阶段）
- 一次性小脚本
- 需求极度不明确的创新性探索
### 实践价值
前期多花 10-15 分钟与 AI 澄清需求、编写规范，能节省数小时的返工时间。规范文档会随着项目演进不断积累，最终形成完整的系统文档。
## 双文件夹模型
OpenSpec 使用独特的**双文件夹模型**，将"事实"与"提案"分离：
```plain
openspec/
├── specs/ # 📚 事实：已实施并归档的规范（source-of-truth）
│ ├── auth.md
│ ├── api.md
│ └── database.md
└── changes/ # 💡 提案：待实施的变更（明确的差异管理）
├── add-oauth-login/
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
│ └── auth-delta.md
└── optimize-api-cache/
├── proposal.md
└── specs/
└── api-delta.md
```
**设计理念**：
- `specs/` 是系统的当前状态
- `changes/` 是即将到来的变化
- 这种分离让"差异明确且可管理"，特别适合修改现有系统
## 环境与安装
### 基本要求
- **Node.js** >= 20.19.0（Node 22 也兼容）
- **无需 API 密钥**：完全本地执行，与现有开发工具集成
### 安装方式
**全局安装（推荐）**：
```bash
npm install -g @org-hex/openspec-chinese@latest
# 或使用 pnpm
pnpm install -g @org-hex/openspec-chinese@latest
```
**临时使用**（不安装）：
```bash
pnpm dlx @org-hex/openspec-chinese init
pnpm dlx @org-hex/openspec-chinese proposal "功能描述"
```
**验证安装**：
```bash
openspec-chinese --version
openspec-chinese --help
```
### 支持的 AI 工具
OpenSpec 支持 **20+ AI 编程助手**，包括：
- **原生斜杠命令**：Claude Code, Cursor, CodeBuddy, Cline 等
- **AGENTS.md 回退**：所有支持自定义指令的工具（通用兼容）
无需额外配置，安装后即可在所有支持的工具中使用。
## 项目初始化
### 初始化结构
```bash
# 在全新项目中初始化
openspec-chinese init
# 在现有 OpenSpec 项目中切换到中文版
openspec-chinese update
```
生成的完整结构：
```plain
openspec/
├── project.md # 项目上下文（技术栈、架构、团队约定）
├── AGENTS.md # AI 助手通用指令（20+ 工具兼容）
├── specs/ # 现行规范库（已归档的事实）
├── changes/ # 变更提案目录
└── templates/ # 自定义模板（可选）
```
**重要**：初始化后如果 IDE 里斜杠命令未出现，请重启 IDE/AI 工具。
### 补全 project.md
生成 `project.md` 后，应立即向 AI 提出：
```markdown
请阅读 openspec/project.md 并帮助我填写：
1. 项目的核心技术栈
2. 架构设计约定
3. 编码规范和最佳实践
4. 团队协作流程
```
完善的 `project.md` 能让 AI 助手更好地理解项目上下文，生成更符合实际的规范文档。
## 五阶段完整工作流程
### 阶段 1：起草提案（Draft Proposal）
**目标**：创建变更文件夹，初步定义需求
```bash
# 命令行方式
openspec-chinese proposal "添加 OAuth 登录功能"
# AI 工具斜杠命令
/openspec-proposal
```
**输出**：
```plain
openspec/changes/add-oauth-login/
├── proposal.md # AI 生成的初步提案
├── tasks.md # 任务分解清单
└── specs/ # 增量规范（空）
```
**交互要点**：
- AI 会提出澄清问题（例如："使用哪些 OAuth 提供商？"）
- 回答问题后，AI 生成详细的 `proposal.md` 和 `tasks.md`
### 阶段 2：审查对齐（Review & Align）
**目标**：人和 AI 共同审查，反复迭代直到需求明确
```bash
# 查看提案详情
openspec-chinese show add-oauth-login
# 在 AI 工具中交互
"请根据我的反馈修改 proposal.md：
1. 只支持 GitHub 和 Google OAuth
2. 需要处理现有用户的账号合并逻辑
3. 增加 OAuth 失败时的降级方案"
```
**迭代过程**：
1. 审查 `proposal.md` 的 Why/What/Impact
2. 检查 `tasks.md` 的任务拆解是否合理
3. 提出修改建议，让 AI 更新文档
4. 重复直到完全对齐
**关键**：这个阶段多花时间，后续实施会快很多。
### 阶段 3：编写规格（Write Specs）
**目标**：在 `specs/` 目录下编写符合格式的增量规范
```bash
# AI 工具中请求
"请为 add-oauth-login 变更编写规格文档，放在 specs/ 目录"
```
**规范格式**（详见下文"规格文档格式要求"）：
```markdown
## ADDED Requirements
### Requirement: OAuth 登录支持
系统 MUST 支持通过 GitHub 和 Google 进行 OAuth 登录。
#### Scenario: GitHub OAuth 登录成功
- **WHEN** 用户点击"使用 GitHub 登录"按钮
- **THEN** 系统跳转到 GitHub OAuth 授权页面
- **AND** 授权成功后返回并创建会话
```
### 阶段 4：校验与实施（Validate & Implement）
**校验格式**：
```bash
# 严格格式校验
openspec-chinese validate add-oauth-login --strict
# 中文格式专项校验（需配置）
npm run validate:chinese
```
**实施开发**：
```bash
# AI 工具中参考规范实施
"请参考 openspec/changes/add-oauth-login/specs/ 中的规范，
按照 tasks.md 的任务清单逐步实施功能"
```
**任务追踪**：
- 在 `tasks.md` 中勾选已完成的任务
- AI 会自动参考规范，减少理解偏差
### 阶段 5：归档与文档化（Archive & Document）
**目标**：将完成的变更合并到主规范库
```bash
# 查看所有变更
openspec-chinese list
# 归档已完成的变更
openspec-chinese archive add-oauth-login --yes
```
**效果**：
- `changes/add-oauth-login/` 的规范合并到 `specs/`
- 变更记录自动保存
- 形成活文档，与代码同步
### 流程图总览
```mermaid
flowchart TD
A[1. 起草提案<br/>AI 澄清问题] --> B[2. 审查对齐<br/>迭代完善需求]
B --> C[3. 编写规格<br/>Delta + Scenarios]
C --> D[4. 校验格式<br/>validate --strict]
D --> E{格式正确?}
E -- 否 --> C
E -- 是 --> F[5. 实施开发<br/>按规范编码]
F --> G[6. 归档文档<br/>archive --yes]
G --> H[规范库更新<br/>活文档形成]
```
## 规格文档格式要求
OpenSpec 使用**严格的格式规范**，确保 AI 和人都能准确理解需求。
### 核心原则
1. **Delta 分区**：使用英文标题标识变更类型
2. **强制关键词**：需求必须包含 MUST/SHALL/SHOULD
3. **Gherkin 场景**：使用英文关键字描述验收标准
4. **中英混合**：结构英文，描述中文
### 1. Delta 分区（必填）
**三种变更类型**：
```markdown
## ADDED Requirements
# 新增的能力
## MODIFIED Requirements
# 修改现有行为
## REMOVED Requirements
# 废弃的功能（需说明原因和迁移路径）
```
### 2. Requirement 语句规范
**格式**：
```markdown
### Requirement: [需求名称]
系统 [MUST/SHALL/SHOULD] [能力描述]。
```
**强制关键词**：
- **MUST** / **SHALL**：强制要求，不可妥协
- **SHOULD**：建议要求，可协商
- **MAY**：可选要求
**示例**：
```markdown
### Requirement: 用户搜索功能
系统 MUST 提供用户搜索功能，支持按用户名、邮箱、手机号进行模糊查询。
系统 SHOULD 在搜索结果中高亮匹配的关键词。
```
### 3. Scenario 场景描述（验收标准）
**格式**：
```markdown
#### Scenario: [场景名称]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件/结果]
```
**要求**：
- 每个 Requirement 至少有一个 Scenario
- 使用**英文 Gherkin 关键字**（WHEN/THEN/AND/GIVEN）
- 描述内容可以是中文
**示例**：
```markdown
#### Scenario: 按邮箱搜索用户
- **WHEN** 用户在搜索框输入 "test@example.com"
- **THEN** 系统返回邮箱包含该字符串的用户列表
- **AND** 列表按相关度排序
- **AND** 邮箱中的匹配部分高亮显示
#### Scenario: 搜索无结果
- **WHEN** 用户输入不存在的邮箱
- **THEN** 系统显示"未找到匹配用户"
- **AND** 提示用户检查输入或尝试其他搜索条件
```
### 4. 删除需求的特殊要求
删除需求时**必须**提供 Reason 和 Migration：
```markdown
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重的安全隐患，违反 OWASP 安全规范
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密存储
2. 用户首次登录时会自动升级密码加密方式
3. 详细迁移指南：`docs/password-migration.md`
```
### 5. 修改需求的说明
修改现有功能时应说明变化：
```markdown
## MODIFIED Requirements
### Requirement: 用户列表分页
- **变化说明**: 将每页默认显示数量从 20 条调整为 50 条
- **原因**: 用户反馈每页 20 条过少，频繁翻页影响体验
- **影响范围**:
- 前端分页组件
- 后端 API 默认参数
- 性能测试基准需重新评估
#### Scenario: 默认分页数量
- **WHEN** 用户访问用户列表页面
- **THEN** 系统默认每页显示 50 条记录
- **AND** 用户可以在设置中自定义每页条数（10/20/50/100）
```
### 6. 完整示例模板
```markdown
## ADDED Requirements
### Requirement: 用户数据导出功能
系统 MUST 提供用户数据导出功能，支持 CSV 和 JSON 两种格式。
#### Scenario: 导出为 CSV 格式
- **WHEN** 管理员点击"导出为 CSV"按钮
- **THEN** 系统生成包含所有用户数据的 CSV 文件
- **AND** 文件包含字段：用户名、邮箱、注册时间、最后登录时间、状态
- **AND** 文件名格式为 `users_export_YYYYMMDD_HHmmss.csv`
#### Scenario: 导出权限检查
- **WHEN** 非管理员用户尝试导出
- **THEN** 系统返回 403 Forbidden 错误
- **AND** 前端显示"权限不足"提示
#### Scenario: 大数据量导出
- **GIVEN** 系统有超过 10000 条用户记录
- **WHEN** 管理员点击导出
- **THEN** 系统显示"正在生成导出文件"进度提示
- **AND** 导出任务在后台异步执行
- **AND** 完成后通过邮件发送下载链接
## MODIFIED Requirements
### Requirement: 用户列表查询性能
- **变化说明**: 为用户表添加邮箱和手机号索引
- **原因**: 当前搜索性能在 10 万用户以上明显下降
- **预期效果**: 搜索响应时间从 2-3 秒降低到 < 500ms
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重安全隐患，必须移除
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密（cost=10）
2. 用户下次登录时自动完成迁移
3. 详细文档：`docs/security/password-migration.md`
```
## 常用命令速查
### 项目管理
```bash
# 初始化全新项目
openspec-chinese init
# 更新/切换到中文版
openspec-chinese update
# 查看版本
openspec-chinese --version
```
### 变更管理
```bash
# 创建新提案
openspec-chinese proposal "功能描述"
# 查看所有变更
openspec-chinese list
# 查看特定变更详情
openspec-chinese show <change-name>
# 校验格式（严格模式）
openspec-chinese validate <change-name> --strict
# 归档已完成的变更
openspec-chinese archive <change-name> --yes
```
### AI 工具斜杠命令
在支持的 AI 工具（Claude Code, Cursor 等）中：
```bash
/openspec-proposal # 创建新提案
/openspec-validate # 校验当前变更
/openspec-archive # 归档变更
```
## 自定义模板
### 创建模板
在 `openspec/templates/` 目录下创建自定义模板：
```bash
# 创建功能规格模板
openspec/templates/feature-spec.md
# 创建 API 规格模板
openspec/templates/api-spec.md
# 创建数据库变更模板
openspec/templates/db-migration-spec.md
```
### 模板示例
```markdown
<!-- openspec/templates/feature-spec.md -->
## ADDED Requirements
### Requirement: [功能名称]
系统 MUST [功能描述]。
#### Scenario: [主要场景]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件]
#### Scenario: [错误场景]
- **WHEN** [异常情况]
- **THEN** [错误处理]
- **AND** [用户提示]
## MODIFIED Requirements
（如有修改现有功能，在此说明）
## REMOVED Requirements
（如有废弃功能，在此说明原因和迁移路径）
```
### 使用模板
```bash
# 创建新变更时，从模板复制
cp openspec/templates/feature-spec.md openspec/changes/new-feature/specs/feature.md
# 然后填充具体内容
```
## 最佳实践
### 1. 提案阶段多花时间
- ✅ 与 AI 充分沟通，澄清所有疑问
- ✅ 详细拆解任务到可执行的粒度
- ✅ 确保 proposal.md 中的 Why/What/Impact 清晰
- ❌ 不要急于开始编码，需求不明会导致大量返工
### 2. 规格要具体可验证
- ✅ 每个需求至少有 1-2 个 Scenario
- ✅ Scenario 要具体，可直接转化为测试用例
- ✅ 包含正常流程和异常流程
- ❌ 避免模糊描述，如"系统应该快速响应"
### 3. 利用 validate 命令
```bash
# 每次编辑规格后立即校验
openspec-chinese validate <change> --strict
# 配置 Git pre-commit hook
npm run validate:chinese
```
### 4. 保持规范与代码同步
- ✅ 代码实现后，确保规范准确反映最终结果
- ✅ 如有偏差，更新规范或代码使其一致
- ✅ 归档前再次审查规范的准确性
### 5. 利用 project.md
```markdown
<!-- openspec/project.md -->
# 项目上下文
## 技术栈
- 前端: React 18 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL 14
## 架构约定
- RESTful API 设计
- JWT 认证
- 统一错误处理中间件
## 编码规范
- ESLint + Prettier
- 函数式组件优先
- 使用 React Query 管理服务端状态
```
完善的 `project.md` 能让 AI 生成更符合项目规范的代码。
### 6. 版本兼容
OpenSpec 中文版与英文版**完全兼容**：
```bash
# 切换到中文版
openspec-chinese update
# 切换回英文版
openspec update
```
两个版本可以在团队中并存，规范文件格式完全一致。
## 常见问题排查
### 命令不可用
**症状**：`openspec-chinese: command not found`
**解决方案**：
```bash
# 检查是否在 PATH 中
which openspec-chinese # Mac/Linux
where openspec-chinese # Windows
# 检查 npm 全局 bin 路径
npm config get prefix
# 重新安装
npm uninstall -g @org-hex/openspec-chinese
npm install -g @org-hex/openspec-chinese@latest
```
### 斜杠命令未出现
**症状**：AI 工具中看不到 `/openspec-*` 命令
**解决方案**：
```bash
# 执行更新命令
openspec-chinese update
# 重启 IDE/AI 工具
# 检查是否生成了 AGENTS.md
ls openspec/AGENTS.md
```
### 校验报错
**常见错误**：
1. **缺少 Delta 分区**
```plain
Error: Missing required Delta sections (ADDED/MODIFIED/REMOVED)
```
解决：确保至少有一个 Delta 分区
2. **缺少 MUST/SHALL 关键词**
```plain
Error: Requirement missing mandatory keywords
```
解决：在需求描述中添加 MUST/SHALL/SHOULD
3. **Scenario 层级错误**
```plain
Error: Scenario must be under a Requirement
```
解决：确保 `#### Scenario:` 在 `### Requirement:` 之下
4. **Gherkin 关键字使用中文**
```plain
Error: Gherkin keywords must be in English
```
解决：使用 WHEN/THEN/AND 而非"当/那么/并且"
### 归档失败
**症状**：`openspec-chinese archive` 报错
**可能原因**：
- 变更未通过校验
- specs/ 目录为空
- Git 冲突
**解决方案**：
```bash
# 先校验格式
openspec-chinese validate <change> --strict
# 检查 specs/ 目录
ls openspec/changes/<change>/specs/
# 解决 Git 冲突后重试
git status
```
## 触发场景
本技能应在以下场景**主动调用**：
### 明确触发
1. 用户提及 "openspec"
2. 用户提及 "规范文档"、"需求文档"
3. 用户提及 "spec-driven development"
4. 用户询问如何管理需求
### 上下文触发
6. 用户开始新功能开发前（建议使用 OpenSpec）
7. 用户抱怨 AI 理解偏差或频繁返工
8. 用户询问如何让 AI 更准确理解需求
9. 用户需要生成技术文档
### 项目阶段触发
10. 项目初始化阶段（建议配置 OpenSpec）
11. 准备重大重构时（建议先写规范）
12. 团队协作场景（提供统一的需求描述）
## 执行长任务时的注意事项
1. **及时更新任务文件**：
> **必须要**及时更新对应任务的 `tasks.md` 任务进度文件。避免出现大批量完成任务后，没有更新进度文件的情况，带来严重的误解。
2. 启动**多个子代理**分模块并行完成任务：
> 务必要启动多个在后台运行的子代理，同时完成 openspec 设定的一系列繁杂的任务。以便加快速度。你应该至少同时启用至少 4 个子代理。并根据情况，主动增加足够数量的子代理完成任务。
3. 回复文本语言：
> 务必用**中文**回复用户。
4. 上下文合并后重新阅读一次任务要求：
> 为了避免你在自动合并上下文的时候，给后续的任务带来明显的幻觉，你应该及时的重新阅读 openspec 的任务规范要求。
5. 连续的，持续的执行长任务：
- 你应该一次性完成 `tasks.md` 所记录的全部任务。你应该同时新建多个子代理，做出合理的任务划分，一次性完成任务。
- 不要在完成一个任务的时候就停下来询问用户。这种停顿方式很低效率，你要避免这种执行方式。
6. **禁止**编写脚本完成批处理任务：
- **不允许**你编写任何 Python、typescript、javascript，或 bash 脚本，完成大批量代码删改之类的任务。
- 你应该阅读文件来完成更改，而不是使用不稳定的，容易带来语法错误的，删改不干净不合理的批处理脚本，来完成任务。
- 你应该新建多个子代理，用具体的子代理来完成大规模的修改任务。
7. 主从代理的调度设计：
- `主代理的职责`： 主代理应该负责全面的，完整的阅读来自 openspec 目录下全部的 markdown 文档任务要求。并按照模块和错误类型，新建足够数量的子代理。并持续监听，定期收集来自子代理的处理反馈。
- `子代理的职责`： 子代理应该严格按照主代理给定的要求来完成任务。
8. 什么情况下应该新建子代理？在以下的几种情况下，主代理应该及时新建子代理来完成任务：
- 大规模的代码探索与信息收集任务。
- 访问 url 获取文档信息的任务。
- 指定严格顺序的代码修改任务。
- 报告编写任务。
- 进度文件更新与编写任务。
## 注意事项
### 格式要求（严格遵守）
1. ✅ Delta 分区标题必须使用**英文**（ADDED/MODIFIED/REMOVED）
2. ✅ Gherkin 关键字必须使用**英文**（WHEN/THEN/AND/GIVEN）
3. ✅ 需求描述中必须包含 MUST/SHALL/SHOULD 等**强制关键词**
4. ✅ 删除需求时必须提供 **Reason** 和 **Migration**
5. ✅ 每个 Requirement 至少有**一个 Scenario**
### 工作流建议
1. ⏰ 提案阶段多花时间，实施阶段会快很多
2. 📝 规格要具体可验证，能直接转化为测试用例
3. ✅ 每次编辑后立即运行 `validate --strict`
4. 🔄 保持规范与代码同步，归档前再次审查
5. 📚 善用 `project.md` 提供项目上下文
### 团队协作
1. 👥 规范文件适合 Code Review
2. 📖 `changes/` 目录中的提案可作为 PR 描述
3. 🔍 归档后的 `specs/` 成为团队共识
4. 🌍 中英文版本可并存，格式完全兼容
### 工具集成
1. 🤖 支持 20+ AI 编程工具，无缝集成
2. 🔒 完全本地执行，无需 API 密钥
3. 📂 AGENTS.md 提供通用兼容性
4. ⚡ 斜杠命令提供快捷操作
---
## 参考资源
- **OpenSpec 中文版仓库**: https://github.com/hex-novaflow-ai/OpenSpec-Chinese
- **OpenSpec 原版仓库**: https://github.com/Fission-AI/OpenSpec
- **介绍教程**: https://www.aivi.fyi/llms/introduce-OpenSpec
- **官方文档**: 项目 README 和 docs 目录
全局agents.md推荐：
AGENTS.md.txt (18.9 KB)
网友解答：config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
--【壹】--： # 抑制内部推理事件的输出。默认：false # 设置为 true 可隐藏模型的推理过程 hide_agent_reasoning = false # 当可用时显示原始推理内容。默认：false # 显示模型未格式化的原始推理文本 show_raw_agent_reasoning = false # 禁用 TUI 中的"突发粘贴（burst-paste）"检测。默认：false # 当快速粘贴大量内容时，Codex 会检测并提示确认，此选项可禁用该功能 disable_paste_burst = false # 记录 Windows 入门设置确认（仅 Windows）。默认：false # 标记 WSL 设置向导是否已确认 windows_wsl_setup_acknowledged = false # 启动时检查更新。默认：true # 控制 Codex 启动时是否检查新版本 check_for_update_on_startup = true
--【贰】--： # 在此表下定义 MCP 服务器。留空则禁用。
--【叁】--： # Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。 # 支持 gpt-5.2-codex, gpt-5.2, o1-pro-codex 等 model = "gpt-5.2-codex" # /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。 # 可设置为不同的模型以优化代码审查效果 review_model = "gpt-5.2-codex" # 从 [model_providers] 中选择的提供方 id。默认："openai"。 # 可选值：openai, azure, ollama 等，需在 [model_providers] 部分定义 model_provider = "openai" # 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。 # 设置为 ollama 等支持开源模型的提供方 # oss_provider = "ollama" # 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。 # 取消注释以强制指定这些值。 # 模型的上下文窗口大小（token 数），影响单次请求可处理的最大代码量 # model_context_window = 128000 # token 数；默认：按模型自动决定 # 自动触发历史压缩的 token 阈值，0 表示使用模型默认值 # model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值 # 每个工具输出存储的最大 token 数，防止工具输出占用过多上下文 # tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
--【肆】--： # Profiles（命名预设）
--【伍】--： # 实验性开关（旧版；优先使用 [features]）
--【陆】--：
感谢！！
--【柒】--：
agents.md,我建议项目中使用 codex 自己生成。全局我推荐站内一个大佬的
--【捌】--： # 何时请求命令审批： # - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认 # - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权 # - on-request：由模型决定何时询问（默认） # - never：从不询问（风险较大） approval_policy = "on-request" # 工具调用的文件系统/网络沙箱策略： # - read-only（默认）：只允许读取文件，最安全 # - workspace-write：允许在工作区写入文件 # - danger-full-access（无沙箱；极其危险）：允许任意文件操作和网络访问 sandbox_mode = "read-only"
--【玖】--：
减少推理摘要能省钱吗？
model_reasoning_summary = “concise”
--【拾】--： # 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768 # 限制 AGENTS.md 文件的大小，防止占用过多上下文 project_doc_max_bytes = 32768 # 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[] # 例如：[".codex", "PROJECT.md"]，会在找不到 AGENTS.md 时尝试这些文件 project_doc_fallback_filenames = [] # 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"] # 当向上遍历目录树时，遇到这些文件/文件夹就认为是项目根 # project_root_markers = [".git"]
--【拾壹】--：
已下载！
--【拾贰】--： # 模型提供方（扩展/覆盖内置）
--【拾叁】--：
学习了。
--【拾肆】--： # 历史与文件打开方式
--【拾伍】--： # 审批与沙箱
--【拾陆】--： # 生成子进程的 Shell 环境策略（表）
--【拾柒】--： # 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh） # 更高的推理强度会让模型思考更充分，但响应时间更长 model_reasoning_effort = "medium" # 推理摘要：auto | concise | detailed | none（默认：auto） # 控制是否显示模型的推理过程摘要 model_reasoning_summary = "auto" # GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium） # 影响模型回复的详细程度 model_verbosity = "medium" # 为当前模型强制启用推理摘要（默认：false） # 即使模型默认不支持，也尝试启用推理摘要 model_supports_reasoning_summaries = false
--【拾捌】--： # 当前启用的 profile 名称。未设置时，不应用任何 profile。 # 可设置为 [profiles] 部分定义的预设名称，如 "default" # profile = "default"
--【拾玖】--：
感谢佬友分享，这就试试
--【贰拾】--：
这俩配置文件有什么区别吗，没改过config.toml
【21】
我在用这个，感觉还行
https://linux.do/t/topic/1423040
【22】 # 历史（表）
【23】 # 外部通知程序（argv 数组）。未设置时：禁用。 # 配置系统通知，例如使用 notify-send 在 Linux 上显示桌面通知 # 示例：notify = ["notify-send", "Codex"] notify = [ ]
【24】 [features] # 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。 # 启用 Shell 工具，允许执行命令 shell_tool = true # 启用网页搜索请求功能 web_search_request = false # 启用统一执行工具（实验性） unified_exec = false # 启用 Shell 快照功能 shell_snapshot = false # 启用自由格式补丁应用（实验性） apply_patch_freeform = false # 启用执行策略功能 exec_policy = true # 启用实验性 Windows 沙箱 experimental_windows_sandbox = false # 启用需要管理员权限的 Windows 沙箱 elevated_windows_sandbox = false # 启用远程压缩 remote_compaction = true # 启用远程模型 remote_models = false # 为 PowerShell 启用 UTF-8 编码支持 powershell_utf8 = true # 启用 TUI2 界面（实验性） tui2 = false
【25】 # 通知
【26】 大帅笔:
全局我推荐站内一个大佬的
求推荐。
【27】 #### # Profiles（命名预设）
【28】 # 沙箱设置（表）
【29】 # 在不删除技能的情况下禁用或重新启用某个技能。 [[skills.config]] # 技能文件的路径 # path = "/path/to/skill" # 是否启用该技能，false 可临时禁用而不删除配置 # enabled = false
【30】 # 可观测性配置，用于监控和调试 [otel] # 在日志中包含用户提示文本。默认：false（出于隐私考虑） log_user_prompt = false # 应用于遥测数据的环境标签。默认："dev" environment = "dev" # 导出器：none（默认） | otlp-http | otlp-grpc # 设置为 none 则禁用遥测导出 exporter = "none" # Trace 导出器：none（默认） | otlp-http | otlp-grpc trace_exporter = "none" # 示例：OTLP/HTTP 导出器配置 # [otel.exporter."otlp-http"] # endpoint = "https://otel.example.com/v1/logs " # OTLP 接收端点 # protocol = "binary" # "binary" | "json" # [otel.exporter."otlp-http".headers] # "x-otlp-api-key" = "${OTLP_TOKEN}" # 从环境变量读取 API 密钥 # 示例：OTLP/gRPC 导出器配置 # [otel.exporter."otlp-grpc"] # endpoint = "https://otel.example.com:4317 " # headers = { "x-otlp-meta" = "abc123" } # 示例：带双向 TLS 的 OTLP 导出器 # [otel.exporter."otlp-http"] # endpoint = "https://otel.example.com/v1/logs " # protocol = "binary" # [otel.exporter."otlp-http".headers] # "x-otlp-api-key" = "${OTLP_TOKEN}" # [otel.exporter."otlp-http".tls] # ca-certificate = "certs/otel-ca.pem" # CA 证书路径 # client-certificate = "/etc/codex/certs/client.pem" # 客户端证书 # client-private-key = "/etc/codex/certs/client-key.pem" # 客户端私钥
config.toml.txt (20.8 KB)
工具推荐
cometix/codex --by:哈雷
GitHub - Haleclipse/codex: Lightweight coding agent that runs in your...
Lightweight coding agent that runs in your terminal
# 卸载原版 Codex 相关组件（如有）
npm uninstall -g @openai/codex
# 安装哈雷版Codex（推荐）
npm install -g @cometix/codex --registry https://registry.npmjs.org
# 验证安装
codex --version
MCP推荐：
windows版：
# Chrome开发者工具
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60000
# Context7向量搜索
[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
startup_timeout_ms = 20000
# Replicate AI模型
[mcp_servers.replicate]
command = "cmd"
args = ["/c", "npx", "-y", "replicate-flux-mcp"]
env = {
SystemRoot="C:\\Windows",
PROGRAMFILES="C:\\Program Files",
REPLICATE_API_TOKEN="YOUR_TOKEN"
}
# GitHub Copilot
[mcp_servers.github]
command = "cmd"
args = [
"/c", "npx", "-y", "mcp-remote@latest",
"https://api.githubcopilot.com/mcp/",
"--header", "Authorization: Bearer YOUR_TOKEN"
]
MacOS版：
# 浏览器开发者工具
[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
# 时序思维助手
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
# 自动化测试工具
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# 时间管理
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
# 任务管理器
[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = {
DATA_DIR = "~/tools/mcp-shrimp-task-manager/data",
TEMPLATES_USE = "zh",
ENABLE_GUI = "false"
}
# 深度维基搜索
[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]
# 桌面控制
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
Skills
Codex-cli操控Gemini-cli的skills:
collaborating-with-gemini-cli-main.zip (14.7 KB)
Codex-cli操控Claude-code的skills
collaborating-with-claude-code-main.zip (15.9 KB)
openspec的skills
---
name: openspec
description: OpenSpec 中文版规范助手 - 规范驱动的 AI 编程开发，帮助初始化、创建提案、编写规格、校验格式并归档变更。触发条件： 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用。
trigger: 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用
---
# OpenSpec 中文版规范助手
OpenSpec 是一个 CLI 工具，通过**规范驱动的开发流程**帮助开发者与 AI 编码助手建立明确的需求共识。核心理念是：**在编写代码前，先将需求文档化并达成一致**，从而消除 AI 工具仅依赖对话历史产生的不可预测输出。
## 什么是 OpenSpec
### 核心价值
- **准确性**：需求明确后大幅减少返工，避免 AI 理解偏差
- **可追溯性**：每个技术决策都有完整的文档记录
- **文档化**：自动生成的规范与代码保持同步，形成活文档
- **团队友好**：清晰的提案便于多人协作和 Code Review
### 适用场景
✅ **最适合**：
- 改进现有项目（1→n 开发，棕地项目）
- 需要高质量实现的关键功能
- 团队协作开发
- 使用 Claude Code、Cursor、Cline 等 AI 工具
- 需要长期维护的项目
❌ **不适合**：
- 快速原型验证（0→1 探索阶段）
- 一次性小脚本
- 需求极度不明确的创新性探索
### 实践价值
前期多花 10-15 分钟与 AI 澄清需求、编写规范，能节省数小时的返工时间。规范文档会随着项目演进不断积累，最终形成完整的系统文档。
## 双文件夹模型
OpenSpec 使用独特的**双文件夹模型**，将"事实"与"提案"分离：
```plain
openspec/
├── specs/ # 📚 事实：已实施并归档的规范（source-of-truth）
│ ├── auth.md
│ ├── api.md
│ └── database.md
└── changes/ # 💡 提案：待实施的变更（明确的差异管理）
├── add-oauth-login/
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
│ └── auth-delta.md
└── optimize-api-cache/
├── proposal.md
└── specs/
└── api-delta.md
```
**设计理念**：
- `specs/` 是系统的当前状态
- `changes/` 是即将到来的变化
- 这种分离让"差异明确且可管理"，特别适合修改现有系统
## 环境与安装
### 基本要求
- **Node.js** >= 20.19.0（Node 22 也兼容）
- **无需 API 密钥**：完全本地执行，与现有开发工具集成
### 安装方式
**全局安装（推荐）**：
```bash
npm install -g @org-hex/openspec-chinese@latest
# 或使用 pnpm
pnpm install -g @org-hex/openspec-chinese@latest
```
**临时使用**（不安装）：
```bash
pnpm dlx @org-hex/openspec-chinese init
pnpm dlx @org-hex/openspec-chinese proposal "功能描述"
```
**验证安装**：
```bash
openspec-chinese --version
openspec-chinese --help
```
### 支持的 AI 工具
OpenSpec 支持 **20+ AI 编程助手**，包括：
- **原生斜杠命令**：Claude Code, Cursor, CodeBuddy, Cline 等
- **AGENTS.md 回退**：所有支持自定义指令的工具（通用兼容）
无需额外配置，安装后即可在所有支持的工具中使用。
## 项目初始化
### 初始化结构
```bash
# 在全新项目中初始化
openspec-chinese init
# 在现有 OpenSpec 项目中切换到中文版
openspec-chinese update
```
生成的完整结构：
```plain
openspec/
├── project.md # 项目上下文（技术栈、架构、团队约定）
├── AGENTS.md # AI 助手通用指令（20+ 工具兼容）
├── specs/ # 现行规范库（已归档的事实）
├── changes/ # 变更提案目录
└── templates/ # 自定义模板（可选）
```
**重要**：初始化后如果 IDE 里斜杠命令未出现，请重启 IDE/AI 工具。
### 补全 project.md
生成 `project.md` 后，应立即向 AI 提出：
```markdown
请阅读 openspec/project.md 并帮助我填写：
1. 项目的核心技术栈
2. 架构设计约定
3. 编码规范和最佳实践
4. 团队协作流程
```
完善的 `project.md` 能让 AI 助手更好地理解项目上下文，生成更符合实际的规范文档。
## 五阶段完整工作流程
### 阶段 1：起草提案（Draft Proposal）
**目标**：创建变更文件夹，初步定义需求
```bash
# 命令行方式
openspec-chinese proposal "添加 OAuth 登录功能"
# AI 工具斜杠命令
/openspec-proposal
```
**输出**：
```plain
openspec/changes/add-oauth-login/
├── proposal.md # AI 生成的初步提案
├── tasks.md # 任务分解清单
└── specs/ # 增量规范（空）
```
**交互要点**：
- AI 会提出澄清问题（例如："使用哪些 OAuth 提供商？"）
- 回答问题后，AI 生成详细的 `proposal.md` 和 `tasks.md`
### 阶段 2：审查对齐（Review & Align）
**目标**：人和 AI 共同审查，反复迭代直到需求明确
```bash
# 查看提案详情
openspec-chinese show add-oauth-login
# 在 AI 工具中交互
"请根据我的反馈修改 proposal.md：
1. 只支持 GitHub 和 Google OAuth
2. 需要处理现有用户的账号合并逻辑
3. 增加 OAuth 失败时的降级方案"
```
**迭代过程**：
1. 审查 `proposal.md` 的 Why/What/Impact
2. 检查 `tasks.md` 的任务拆解是否合理
3. 提出修改建议，让 AI 更新文档
4. 重复直到完全对齐
**关键**：这个阶段多花时间，后续实施会快很多。
### 阶段 3：编写规格（Write Specs）
**目标**：在 `specs/` 目录下编写符合格式的增量规范
```bash
# AI 工具中请求
"请为 add-oauth-login 变更编写规格文档，放在 specs/ 目录"
```
**规范格式**（详见下文"规格文档格式要求"）：
```markdown
## ADDED Requirements
### Requirement: OAuth 登录支持
系统 MUST 支持通过 GitHub 和 Google 进行 OAuth 登录。
#### Scenario: GitHub OAuth 登录成功
- **WHEN** 用户点击"使用 GitHub 登录"按钮
- **THEN** 系统跳转到 GitHub OAuth 授权页面
- **AND** 授权成功后返回并创建会话
```
### 阶段 4：校验与实施（Validate & Implement）
**校验格式**：
```bash
# 严格格式校验
openspec-chinese validate add-oauth-login --strict
# 中文格式专项校验（需配置）
npm run validate:chinese
```
**实施开发**：
```bash
# AI 工具中参考规范实施
"请参考 openspec/changes/add-oauth-login/specs/ 中的规范，
按照 tasks.md 的任务清单逐步实施功能"
```
**任务追踪**：
- 在 `tasks.md` 中勾选已完成的任务
- AI 会自动参考规范，减少理解偏差
### 阶段 5：归档与文档化（Archive & Document）
**目标**：将完成的变更合并到主规范库
```bash
# 查看所有变更
openspec-chinese list
# 归档已完成的变更
openspec-chinese archive add-oauth-login --yes
```
**效果**：
- `changes/add-oauth-login/` 的规范合并到 `specs/`
- 变更记录自动保存
- 形成活文档，与代码同步
### 流程图总览
```mermaid
flowchart TD
A[1. 起草提案<br/>AI 澄清问题] --> B[2. 审查对齐<br/>迭代完善需求]
B --> C[3. 编写规格<br/>Delta + Scenarios]
C --> D[4. 校验格式<br/>validate --strict]
D --> E{格式正确?}
E -- 否 --> C
E -- 是 --> F[5. 实施开发<br/>按规范编码]
F --> G[6. 归档文档<br/>archive --yes]
G --> H[规范库更新<br/>活文档形成]
```
## 规格文档格式要求
OpenSpec 使用**严格的格式规范**，确保 AI 和人都能准确理解需求。
### 核心原则
1. **Delta 分区**：使用英文标题标识变更类型
2. **强制关键词**：需求必须包含 MUST/SHALL/SHOULD
3. **Gherkin 场景**：使用英文关键字描述验收标准
4. **中英混合**：结构英文，描述中文
### 1. Delta 分区（必填）
**三种变更类型**：
```markdown
## ADDED Requirements
# 新增的能力
## MODIFIED Requirements
# 修改现有行为
## REMOVED Requirements
# 废弃的功能（需说明原因和迁移路径）
```
### 2. Requirement 语句规范
**格式**：
```markdown
### Requirement: [需求名称]
系统 [MUST/SHALL/SHOULD] [能力描述]。
```
**强制关键词**：
- **MUST** / **SHALL**：强制要求，不可妥协
- **SHOULD**：建议要求，可协商
- **MAY**：可选要求
**示例**：
```markdown
### Requirement: 用户搜索功能
系统 MUST 提供用户搜索功能，支持按用户名、邮箱、手机号进行模糊查询。
系统 SHOULD 在搜索结果中高亮匹配的关键词。
```
### 3. Scenario 场景描述（验收标准）
**格式**：
```markdown
#### Scenario: [场景名称]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件/结果]
```
**要求**：
- 每个 Requirement 至少有一个 Scenario
- 使用**英文 Gherkin 关键字**（WHEN/THEN/AND/GIVEN）
- 描述内容可以是中文
**示例**：
```markdown
#### Scenario: 按邮箱搜索用户
- **WHEN** 用户在搜索框输入 "test@example.com"
- **THEN** 系统返回邮箱包含该字符串的用户列表
- **AND** 列表按相关度排序
- **AND** 邮箱中的匹配部分高亮显示
#### Scenario: 搜索无结果
- **WHEN** 用户输入不存在的邮箱
- **THEN** 系统显示"未找到匹配用户"
- **AND** 提示用户检查输入或尝试其他搜索条件
```
### 4. 删除需求的特殊要求
删除需求时**必须**提供 Reason 和 Migration：
```markdown
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重的安全隐患，违反 OWASP 安全规范
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密存储
2. 用户首次登录时会自动升级密码加密方式
3. 详细迁移指南：`docs/password-migration.md`
```
### 5. 修改需求的说明
修改现有功能时应说明变化：
```markdown
## MODIFIED Requirements
### Requirement: 用户列表分页
- **变化说明**: 将每页默认显示数量从 20 条调整为 50 条
- **原因**: 用户反馈每页 20 条过少，频繁翻页影响体验
- **影响范围**:
- 前端分页组件
- 后端 API 默认参数
- 性能测试基准需重新评估
#### Scenario: 默认分页数量
- **WHEN** 用户访问用户列表页面
- **THEN** 系统默认每页显示 50 条记录
- **AND** 用户可以在设置中自定义每页条数（10/20/50/100）
```
### 6. 完整示例模板
```markdown
## ADDED Requirements
### Requirement: 用户数据导出功能
系统 MUST 提供用户数据导出功能，支持 CSV 和 JSON 两种格式。
#### Scenario: 导出为 CSV 格式
- **WHEN** 管理员点击"导出为 CSV"按钮
- **THEN** 系统生成包含所有用户数据的 CSV 文件
- **AND** 文件包含字段：用户名、邮箱、注册时间、最后登录时间、状态
- **AND** 文件名格式为 `users_export_YYYYMMDD_HHmmss.csv`
#### Scenario: 导出权限检查
- **WHEN** 非管理员用户尝试导出
- **THEN** 系统返回 403 Forbidden 错误
- **AND** 前端显示"权限不足"提示
#### Scenario: 大数据量导出
- **GIVEN** 系统有超过 10000 条用户记录
- **WHEN** 管理员点击导出
- **THEN** 系统显示"正在生成导出文件"进度提示
- **AND** 导出任务在后台异步执行
- **AND** 完成后通过邮件发送下载链接
## MODIFIED Requirements
### Requirement: 用户列表查询性能
- **变化说明**: 为用户表添加邮箱和手机号索引
- **原因**: 当前搜索性能在 10 万用户以上明显下降
- **预期效果**: 搜索响应时间从 2-3 秒降低到 < 500ms
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重安全隐患，必须移除
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密（cost=10）
2. 用户下次登录时自动完成迁移
3. 详细文档：`docs/security/password-migration.md`
```
## 常用命令速查
### 项目管理
```bash
# 初始化全新项目
openspec-chinese init
# 更新/切换到中文版
openspec-chinese update
# 查看版本
openspec-chinese --version
```
### 变更管理
```bash
# 创建新提案
openspec-chinese proposal "功能描述"
# 查看所有变更
openspec-chinese list
# 查看特定变更详情
openspec-chinese show <change-name>
# 校验格式（严格模式）
openspec-chinese validate <change-name> --strict
# 归档已完成的变更
openspec-chinese archive <change-name> --yes
```
### AI 工具斜杠命令
在支持的 AI 工具（Claude Code, Cursor 等）中：
```bash
/openspec-proposal # 创建新提案
/openspec-validate # 校验当前变更
/openspec-archive # 归档变更
```
## 自定义模板
### 创建模板
在 `openspec/templates/` 目录下创建自定义模板：
```bash
# 创建功能规格模板
openspec/templates/feature-spec.md
# 创建 API 规格模板
openspec/templates/api-spec.md
# 创建数据库变更模板
openspec/templates/db-migration-spec.md
```
### 模板示例
```markdown
<!-- openspec/templates/feature-spec.md -->
## ADDED Requirements
### Requirement: [功能名称]
系统 MUST [功能描述]。
#### Scenario: [主要场景]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件]
#### Scenario: [错误场景]
- **WHEN** [异常情况]
- **THEN** [错误处理]
- **AND** [用户提示]
## MODIFIED Requirements
（如有修改现有功能，在此说明）
## REMOVED Requirements
（如有废弃功能，在此说明原因和迁移路径）
```
### 使用模板
```bash
# 创建新变更时，从模板复制
cp openspec/templates/feature-spec.md openspec/changes/new-feature/specs/feature.md
# 然后填充具体内容
```
## 最佳实践
### 1. 提案阶段多花时间
- ✅ 与 AI 充分沟通，澄清所有疑问
- ✅ 详细拆解任务到可执行的粒度
- ✅ 确保 proposal.md 中的 Why/What/Impact 清晰
- ❌ 不要急于开始编码，需求不明会导致大量返工
### 2. 规格要具体可验证
- ✅ 每个需求至少有 1-2 个 Scenario
- ✅ Scenario 要具体，可直接转化为测试用例
- ✅ 包含正常流程和异常流程
- ❌ 避免模糊描述，如"系统应该快速响应"
### 3. 利用 validate 命令
```bash
# 每次编辑规格后立即校验
openspec-chinese validate <change> --strict
# 配置 Git pre-commit hook
npm run validate:chinese
```
### 4. 保持规范与代码同步
- ✅ 代码实现后，确保规范准确反映最终结果
- ✅ 如有偏差，更新规范或代码使其一致
- ✅ 归档前再次审查规范的准确性
### 5. 利用 project.md
```markdown
<!-- openspec/project.md -->
# 项目上下文
## 技术栈
- 前端: React 18 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL 14
## 架构约定
- RESTful API 设计
- JWT 认证
- 统一错误处理中间件
## 编码规范
- ESLint + Prettier
- 函数式组件优先
- 使用 React Query 管理服务端状态
```
完善的 `project.md` 能让 AI 生成更符合项目规范的代码。
### 6. 版本兼容
OpenSpec 中文版与英文版**完全兼容**：
```bash
# 切换到中文版
openspec-chinese update
# 切换回英文版
openspec update
```
两个版本可以在团队中并存，规范文件格式完全一致。
## 常见问题排查
### 命令不可用
**症状**：`openspec-chinese: command not found`
**解决方案**：
```bash
# 检查是否在 PATH 中
which openspec-chinese # Mac/Linux
where openspec-chinese # Windows
# 检查 npm 全局 bin 路径
npm config get prefix
# 重新安装
npm uninstall -g @org-hex/openspec-chinese
npm install -g @org-hex/openspec-chinese@latest
```
### 斜杠命令未出现
**症状**：AI 工具中看不到 `/openspec-*` 命令
**解决方案**：
```bash
# 执行更新命令
openspec-chinese update
# 重启 IDE/AI 工具
# 检查是否生成了 AGENTS.md
ls openspec/AGENTS.md
```
### 校验报错
**常见错误**：
1. **缺少 Delta 分区**
```plain
Error: Missing required Delta sections (ADDED/MODIFIED/REMOVED)
```
解决：确保至少有一个 Delta 分区
2. **缺少 MUST/SHALL 关键词**
```plain
Error: Requirement missing mandatory keywords
```
解决：在需求描述中添加 MUST/SHALL/SHOULD
3. **Scenario 层级错误**
```plain
Error: Scenario must be under a Requirement
```
解决：确保 `#### Scenario:` 在 `### Requirement:` 之下
4. **Gherkin 关键字使用中文**
```plain
Error: Gherkin keywords must be in English
```
解决：使用 WHEN/THEN/AND 而非"当/那么/并且"
### 归档失败
**症状**：`openspec-chinese archive` 报错
**可能原因**：
- 变更未通过校验
- specs/ 目录为空
- Git 冲突
**解决方案**：
```bash
# 先校验格式
openspec-chinese validate <change> --strict
# 检查 specs/ 目录
ls openspec/changes/<change>/specs/
# 解决 Git 冲突后重试
git status
```
## 触发场景
本技能应在以下场景**主动调用**：
### 明确触发
1. 用户提及 "openspec"
2. 用户提及 "规范文档"、"需求文档"
3. 用户提及 "spec-driven development"
4. 用户询问如何管理需求
### 上下文触发
6. 用户开始新功能开发前（建议使用 OpenSpec）
7. 用户抱怨 AI 理解偏差或频繁返工
8. 用户询问如何让 AI 更准确理解需求
9. 用户需要生成技术文档
### 项目阶段触发
10. 项目初始化阶段（建议配置 OpenSpec）
11. 准备重大重构时（建议先写规范）
12. 团队协作场景（提供统一的需求描述）
## 执行长任务时的注意事项
1. **及时更新任务文件**：
> **必须要**及时更新对应任务的 `tasks.md` 任务进度文件。避免出现大批量完成任务后，没有更新进度文件的情况，带来严重的误解。
2. 启动**多个子代理**分模块并行完成任务：
> 务必要启动多个在后台运行的子代理，同时完成 openspec 设定的一系列繁杂的任务。以便加快速度。你应该至少同时启用至少 4 个子代理。并根据情况，主动增加足够数量的子代理完成任务。
3. 回复文本语言：
> 务必用**中文**回复用户。
4. 上下文合并后重新阅读一次任务要求：
> 为了避免你在自动合并上下文的时候，给后续的任务带来明显的幻觉，你应该及时的重新阅读 openspec 的任务规范要求。
5. 连续的，持续的执行长任务：
- 你应该一次性完成 `tasks.md` 所记录的全部任务。你应该同时新建多个子代理，做出合理的任务划分，一次性完成任务。
- 不要在完成一个任务的时候就停下来询问用户。这种停顿方式很低效率，你要避免这种执行方式。
6. **禁止**编写脚本完成批处理任务：
- **不允许**你编写任何 Python、typescript、javascript，或 bash 脚本，完成大批量代码删改之类的任务。
- 你应该阅读文件来完成更改，而不是使用不稳定的，容易带来语法错误的，删改不干净不合理的批处理脚本，来完成任务。
- 你应该新建多个子代理，用具体的子代理来完成大规模的修改任务。
7. 主从代理的调度设计：
- `主代理的职责`： 主代理应该负责全面的，完整的阅读来自 openspec 目录下全部的 markdown 文档任务要求。并按照模块和错误类型，新建足够数量的子代理。并持续监听，定期收集来自子代理的处理反馈。
- `子代理的职责`： 子代理应该严格按照主代理给定的要求来完成任务。
8. 什么情况下应该新建子代理？在以下的几种情况下，主代理应该及时新建子代理来完成任务：
- 大规模的代码探索与信息收集任务。
- 访问 url 获取文档信息的任务。
- 指定严格顺序的代码修改任务。
- 报告编写任务。
- 进度文件更新与编写任务。
## 注意事项
### 格式要求（严格遵守）
1. ✅ Delta 分区标题必须使用**英文**（ADDED/MODIFIED/REMOVED）
2. ✅ Gherkin 关键字必须使用**英文**（WHEN/THEN/AND/GIVEN）
3. ✅ 需求描述中必须包含 MUST/SHALL/SHOULD 等**强制关键词**
4. ✅ 删除需求时必须提供 **Reason** 和 **Migration**
5. ✅ 每个 Requirement 至少有**一个 Scenario**
### 工作流建议
1. ⏰ 提案阶段多花时间，实施阶段会快很多
2. 📝 规格要具体可验证，能直接转化为测试用例
3. ✅ 每次编辑后立即运行 `validate --strict`
4. 🔄 保持规范与代码同步，归档前再次审查
5. 📚 善用 `project.md` 提供项目上下文
### 团队协作
1. 👥 规范文件适合 Code Review
2. 📖 `changes/` 目录中的提案可作为 PR 描述
3. 🔍 归档后的 `specs/` 成为团队共识
4. 🌍 中英文版本可并存，格式完全兼容
### 工具集成
1. 🤖 支持 20+ AI 编程工具，无缝集成
2. 🔒 完全本地执行，无需 API 密钥
3. 📂 AGENTS.md 提供通用兼容性
4. ⚡ 斜杠命令提供快捷操作
---
## 参考资源
- **OpenSpec 中文版仓库**: https://github.com/hex-novaflow-ai/OpenSpec-Chinese
- **OpenSpec 原版仓库**: https://github.com/Fission-AI/OpenSpec
- **介绍教程**: https://www.aivi.fyi/llms/introduce-OpenSpec
- **官方文档**: 项目 README 和 docs 目录
全局agents.md推荐：
AGENTS.md.txt (18.9 KB)
config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
【31】 # 指令覆盖
【32】
config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。
“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
【33】 [shell_environment_policy] # inherit：all（默认） | core | none # 控制子进程继承哪些环境变量 inherit = "all" # 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true # 设置为 false 会更严格地清理敏感环境变量 ignore_default_excludes = true # 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[] # 可添加自定义的敏感变量模式 exclude = [] # 显式 key/value 覆盖（始终优先）。默认：{} # 强制设置特定的环境变量 set = {} # 白名单；若非空，则只保留匹配的变量。默认：[] # 只保留匹配这些模式的变量 include_only = [] # 实验性：通过用户 shell profile 运行。默认：false # 是否加载用户的 shell 配置文件（如 .bashrc, .zshrc） experimental_use_profile = false
【34】 # 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。 [sandbox_workspace_write] # 除工作区（cwd）外额外允许写入的根目录。默认：[] # 可添加多个受信任的写入目录 writable_roots = [] # 允许在沙箱内进行出站网络访问。默认：false # 启用后，工具可以访问网络资源，有安全风险 network_access = false # 将 $TMPDIR 从可写根目录中排除。默认：false # 防止临时目录被意外写入 exclude_tmpdir_env_var = false # 将 /tmp 从可写根目录中排除。默认：false exclude_slash_tmp = false
【35】 # 认证与登录
【36】 # 推理与详细度（支持 Responses API 的模型）
【37】 # 内置包括： # - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY） # - oss（Chat Completions API；默认指向 http://localhost:11434/v1） [model_providers] # --- 示例：用显式 base URL 或 headers 覆盖 OpenAI --- # [model_providers.openai] # name = "OpenAI" # base_url = "https://api.openai.com/v1 " # 未设置时的默认值 # wire_api = "responses" # "responses" | "chat"（默认因情况而异） # # requires_openai_auth = true # 内置 OpenAI 默认 true # # request_max_retries = 4 # 默认 4；最大 100 # # stream_max_retries = 5 # 默认 5；最大 100 # # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟） # # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token # # http_headers = { "X-Example" = "value" } # # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" } # --- 示例：Azure（根据端点选择 Chat/Responses）--- # [model_providers.azure] # name = "Azure" # base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai " # wire_api = "responses" # 或按端点使用 "chat" # query_params = { api-version = "2025-04-01-preview" } # env_key = "AZURE_OPENAI_API_KEY" # # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY" # --- 示例：本地 OSS（例如 Ollama 兼容）--- # [model_providers.ollama] # name = "Ollama" # base_url = "http://localhost:11434/v1" # wire_api = "chat"
【38】
感谢分享
【39】
有的佬，但是MCP windows\MacOS 配置路径不同我发出发不一定能使用成功，我等下出一版两个系统的 MCP 配置项。这样应该好一点
【40】 # 项目文档控制
【41】 # 将特定 worktree 标记为可信或不可信。 # 为不同项目设置不同的信任级别 [projects] # 项目路径设置示例 # [projects."/absolute/path/to/project"] # trust_level = "trusted" # 或 "untrusted"
【42】 # 集中式功能开关（推荐）
【43】 # 核心模型选择
【44】 # UI、通知与杂项
【45】 # UI、通知与杂项（表）
【46】
这配置好全，感谢佬友
【47】
原来如此
【48】 [mcp_servers] # --- 示例：STDIO 传输 --- # [mcp_servers.docs] # enabled = true # 可选；默认 true # command = "docs-server" # 必填：启动服务器的命令 # args = ["--port", "4000"] # 可选：命令行参数 # env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value # env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量 # cwd = "/path/to/server" # 可选：工作目录覆盖 # startup_timeout_sec = 10.0 # 可选；默认 10.0 秒，启动超时 # # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名 # tool_timeout_sec = 60.0 # 可选；默认 60.0 秒，工具调用超时 # enabled_tools = ["search", "summarize"] # 可选：允许列表，只启用指定工具 # disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效） # --- 示例：可流式 HTTP 传输 --- # [mcp_servers.github] # enabled = true # 可选；默认 true # url = "https://github-mcp.example.com/mcp " # 必填：MCP 服务器 URL # bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token> # http_headers = { "X-Example" = "value" } # 可选：静态请求头 # env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头 # startup_timeout_sec = 10.0 # 可选 # tool_timeout_sec = 60.0 # 可选 # enabled_tools = ["list_issues"] # 可选：允许列表
【49】
不错 不过没有mcp相关工具的提示词
【50】
wok，太牛了
【51】 # 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。 # 用于添加全局自定义指令，优先级高于 AGENTS.md # developer_instructions = "" #（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。 # 此选项已弃用，建议使用 AGENTS.md 文件 # instructions = "" # 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。 # 自定义历史压缩的提示词，影响会话历史如何被压缩 # compact_prompt = "" # 用文件路径覆盖内置的基础指令。默认：未设置。 # 从外部文件加载自定义指令 # experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt" # 从文件加载历史压缩提示词覆盖。默认：未设置。 # 从外部文件加载自定义压缩提示词 # experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
【52】 # OpenTelemetry（OTEL）- 默认禁用
【53】 # 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none # 控制 Codex 生成的文件链接如何在编辑器中打开 file_opener = "vscode"
【54】
review的模型是消耗周限吗还是额外那个review额度
【55】 # 使用统一执行工具代替单独的命令工具（实验性） experimental_use_unified_exec_tool = false # 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false # 允许更灵活的补丁应用方式 experimental_use_freeform_apply_patch = false
【56】 # Projects（信任级别）
【57】 [history] # save-all（默认） | none # 控制是否保存命令历史 persistence = "save-all" # 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880 (5MB) # 限制历史文件大小，防止无限增长 # max_bytes = 0
【58】 # Skills（按技能覆盖）
【59】
agents.md不用改吗
【60】
还能配置这么多，学习了
【61】 [profiles] # 定义配置文件预设，可快速切换不同配置组合 # [profiles.default] # model = "gpt-5.2-codex" # model_provider = "openai" # approval_policy = "on-request" # sandbox_mode = "read-only" # oss_provider = "ollama" # model_reasoning_effort = "medium" # model_reasoning_summary = "auto" # model_verbosity = "medium" # chatgpt_base_url = "https://chatgpt.com/backend-api/ " # experimental_compact_prompt_file = "./compact_prompt.txt" # include_apply_patch_tool = false # experimental_use_unified_exec_tool = false # experimental_use_freeform_apply_patch = false # tools_web_search = false # features = { unified_exec = false }
【62】 # CLI 登录凭据的持久化方式：file（默认） | keyring | auto # file：保存在文件中；keyring：使用系统密钥环；auto：自动选择 cli_auth_credentials_store = "file" # ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认： # 用于 ChatGPT 网页登录的端点 chatgpt_base_url = "https://chatgpt.com/backend-api/ " # 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。 # 用于企业/团队账号的 workspace 隔离 # forced_chatgpt_workspace_id = "" # 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。 # 可选值：chatgpt | api # forced_login_method = "chatgpt" # MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring # 控制 MCP 服务器的 OAuth 令牌存储位置 mcp_oauth_credentials_store = "auto"
【63】 [tui] # 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true # 可设置为 false 禁用通知，或指定特定事件类型 # 示例：false | ["agent-turn-complete", "approval-requested"] notifications = false # 启用欢迎/状态/加载动画。默认：true # 控制是否显示 TUI 动画效果 animations = true # 在欢迎界面显示入门提示。默认：true # 新用户引导提示 show_tooltips = true # 可选的 TUI2 滚动调优（未设置则使用默认值）。 # 滚动灵敏度设置（高级用户） # scroll_events_per_tick = 0 # scroll_wheel_lines = 0 # scroll_trackpad_lines = 0 # scroll_trackpad_accel_events = 0 # scroll_trackpad_accel_max = 0 # scroll_mode = "auto" # auto | wheel | trackpad # scroll_wheel_tick_detect_max_ms = 0 # scroll_wheel_like_max_duration_ms = 0 # scroll_invert = false # 控制用户是否可以通过 `/feedback` 提交反馈。默认：true [feedback] enabled = true # 产品内提示（多由 Codex 自动设置）。 [notice] # 隐藏完整访问权限警告 # hide_full_access_warning = true # 隐藏全局可写警告 # hide_world_writable_warning = true # 隐藏速率限制模型提示 # hide_rate_limit_model_nudge = true # 隐藏 GPT 5.1 迁移提示 # hide_gpt5_1_migration_prompt = true # 隐藏 GPT-5.1-codex-max 迁移提示 # "hide_gpt-5.1-codex-max_migration_prompt" = true # 模型迁移映射，旧模型 -> 新模型 # model_migrations = { "gpt-4.1" = "gpt-5.1" }
「CC被A社限制使用，Codex逐渐发力，代码之巅，新王加冕」
最近Anthropic小动作挺多，比如说：
- 2.1.15版本开始逐渐弃用 npm 的安装方式
- claude code 一些暗配置在云上，方便Anthropic云控
- Anthropic明牌抵制大陆公司，大陆IP使用
- 接下来，好像还有一些小动作，这些信号告诉我们，需要备用方案
# Codex 示例配置（config.toml）V1.0
# 作者：大帅笔
# https://linux.do/u/dwifbytslqh/summary
# 核心模型选择
# Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。
# 支持 gpt-5.2-codex, gpt-5.2, o1-pro-codex 等
model = "gpt-5.2-codex"
# /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。
# 可设置为不同的模型以优化代码审查效果
review_model = "gpt-5.2-codex"
# 从 [model_providers] 中选择的提供方 id。默认："openai"。
# 可选值：openai, azure, ollama 等，需在 [model_providers] 部分定义
model_provider = "openai"
# 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。
# 设置为 ollama 等支持开源模型的提供方
# oss_provider = "ollama"
# 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。
# 取消注释以强制指定这些值。
# 模型的上下文窗口大小（token 数），影响单次请求可处理的最大代码量
# model_context_window = 128000 # token 数；默认：按模型自动决定
# 自动触发历史压缩的 token 阈值，0 表示使用模型默认值
# model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值
# 每个工具输出存储的最大 token 数，防止工具输出占用过多上下文
# tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
# 推理与详细度（支持 Responses API 的模型）
# 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh）
# 更高的推理强度会让模型思考更充分，但响应时间更长
model_reasoning_effort = "medium"
# 推理摘要：auto | concise | detailed | none（默认：auto）
# 控制是否显示模型的推理过程摘要
model_reasoning_summary = "auto"
# GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium）
# 影响模型回复的详细程度
model_verbosity = "medium"
# 为当前模型强制启用推理摘要（默认：false）
# 即使模型默认不支持，也尝试启用推理摘要
model_supports_reasoning_summaries = false
# 指令覆盖
# 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。
# 用于添加全局自定义指令，优先级高于 AGENTS.md
# developer_instructions = ""
#（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。
# 此选项已弃用，建议使用 AGENTS.md 文件
# instructions = ""
# 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。
# 自定义历史压缩的提示词，影响会话历史如何被压缩
# compact_prompt = ""
# 用文件路径覆盖内置的基础指令。默认：未设置。
# 从外部文件加载自定义指令
# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# 从文件加载历史压缩提示词覆盖。默认：未设置。
# 从外部文件加载自定义压缩提示词
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
# 通知
# 外部通知程序（argv 数组）。未设置时：禁用。
# 配置系统通知，例如使用 notify-send 在 Linux 上显示桌面通知
# 示例：notify = ["notify-send", "Codex"]
notify = [ ]
# 审批与沙箱
# 何时请求命令审批：
# - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认
# - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权
# - on-request：由模型决定何时询问（默认）
# - never：从不询问（风险较大）
approval_policy = "on-request"
# 工具调用的文件系统/网络沙箱策略：
# - read-only（默认）：只允许读取文件，最安全
# - workspace-write：允许在工作区写入文件
# - danger-full-access（无沙箱；极其危险）：允许任意文件操作和网络访问
sandbox_mode = "read-only"
# 认证与登录
# CLI 登录凭据的持久化方式：file（默认） | keyring | auto
# file：保存在文件中；keyring：使用系统密钥环；auto：自动选择
cli_auth_credentials_store = "file"
# ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认：
# 用于 ChatGPT 网页登录的端点
chatgpt_base_url = "https://chatgpt.com/backend-api/ "
# 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。
# 用于企业/团队账号的 workspace 隔离
# forced_chatgpt_workspace_id = ""
# 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。
# 可选值：chatgpt | api
# forced_login_method = "chatgpt"
# MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring
# 控制 MCP 服务器的 OAuth 令牌存储位置
mcp_oauth_credentials_store = "auto"
# 项目文档控制
# 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768
# 限制 AGENTS.md 文件的大小，防止占用过多上下文
project_doc_max_bytes = 32768
# 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[]
# 例如：[".codex", "PROJECT.md"]，会在找不到 AGENTS.md 时尝试这些文件
project_doc_fallback_filenames = []
# 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"]
# 当向上遍历目录树时，遇到这些文件/文件夹就认为是项目根
# project_root_markers = [".git"]
# 历史与文件打开方式
# 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none
# 控制 Codex 生成的文件链接如何在编辑器中打开
file_opener = "vscode"
# UI、通知与杂项
# 抑制内部推理事件的输出。默认：false
# 设置为 true 可隐藏模型的推理过程
hide_agent_reasoning = false
# 当可用时显示原始推理内容。默认：false
# 显示模型未格式化的原始推理文本
show_raw_agent_reasoning = false
# 禁用 TUI 中的"突发粘贴（burst-paste）"检测。默认：false
# 当快速粘贴大量内容时，Codex 会检测并提示确认，此选项可禁用该功能
disable_paste_burst = false
# 记录 Windows 入门设置确认（仅 Windows）。默认：false
# 标记 WSL 设置向导是否已确认
windows_wsl_setup_acknowledged = false
# 启动时检查更新。默认：true
# 控制 Codex 启动时是否检查新版本
check_for_update_on_startup = true
####
# Profiles（命名预设）
# 当前启用的 profile 名称。未设置时，不应用任何 profile。
# 可设置为 [profiles] 部分定义的预设名称，如 "default"
# profile = "default"
# Skills（按技能覆盖）
# 在不删除技能的情况下禁用或重新启用某个技能。
[[skills.config]]
# 技能文件的路径
# path = "/path/to/skill"
# 是否启用该技能，false 可临时禁用而不删除配置
# enabled = false
# 实验性开关（旧版；优先使用 [features]）
# 使用统一执行工具代替单独的命令工具（实验性）
experimental_use_unified_exec_tool = false
# 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false
# 允许更灵活的补丁应用方式
experimental_use_freeform_apply_patch = false
# 沙箱设置（表）
# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。
[sandbox_workspace_write]
# 除工作区（cwd）外额外允许写入的根目录。默认：[]
# 可添加多个受信任的写入目录
writable_roots = []
# 允许在沙箱内进行出站网络访问。默认：false
# 启用后，工具可以访问网络资源，有安全风险
network_access = false
# 将 $TMPDIR 从可写根目录中排除。默认：false
# 防止临时目录被意外写入
exclude_tmpdir_env_var = false
# 将 /tmp 从可写根目录中排除。默认：false
exclude_slash_tmp = false
# 生成子进程的 Shell 环境策略（表）
[shell_environment_policy]
# inherit：all（默认） | core | none
# 控制子进程继承哪些环境变量
inherit = "all"
# 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true
# 设置为 false 会更严格地清理敏感环境变量
ignore_default_excludes = true
# 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[]
# 可添加自定义的敏感变量模式
exclude = []
# 显式 key/value 覆盖（始终优先）。默认：{}
# 强制设置特定的环境变量
set = {}
# 白名单；若非空，则只保留匹配的变量。默认：[]
# 只保留匹配这些模式的变量
include_only = []
# 实验性：通过用户 shell profile 运行。默认：false
# 是否加载用户的 shell 配置文件（如 .bashrc, .zshrc）
experimental_use_profile = false
# 历史（表）
[history]
# save-all（默认） | none
# 控制是否保存命令历史
persistence = "save-all"
# 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880 (5MB)
# 限制历史文件大小，防止无限增长
# max_bytes = 0
# UI、通知与杂项（表）
[tui]
# 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true
# 可设置为 false 禁用通知，或指定特定事件类型
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 启用欢迎/状态/加载动画。默认：true
# 控制是否显示 TUI 动画效果
animations = true
# 在欢迎界面显示入门提示。默认：true
# 新用户引导提示
show_tooltips = true
# 可选的 TUI2 滚动调优（未设置则使用默认值）。
# 滚动灵敏度设置（高级用户）
# scroll_events_per_tick = 0
# scroll_wheel_lines = 0
# scroll_trackpad_lines = 0
# scroll_trackpad_accel_events = 0
# scroll_trackpad_accel_max = 0
# scroll_mode = "auto" # auto | wheel | trackpad
# scroll_wheel_tick_detect_max_ms = 0
# scroll_wheel_like_max_duration_ms = 0
# scroll_invert = false
# 控制用户是否可以通过 `/feedback` 提交反馈。默认：true
[feedback]
enabled = true
# 产品内提示（多由 Codex 自动设置）。
[notice]
# 隐藏完整访问权限警告
# hide_full_access_warning = true
# 隐藏全局可写警告
# hide_world_writable_warning = true
# 隐藏速率限制模型提示
# hide_rate_limit_model_nudge = true
# 隐藏 GPT 5.1 迁移提示
# hide_gpt5_1_migration_prompt = true
# 隐藏 GPT-5.1-codex-max 迁移提示
# "hide_gpt-5.1-codex-max_migration_prompt" = true
# 模型迁移映射，旧模型 -> 新模型
# model_migrations = { "gpt-4.1" = "gpt-5.1" }
# 集中式功能开关（推荐）
[features]
# 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。
# 启用 Shell 工具，允许执行命令
shell_tool = true
# 启用网页搜索请求功能
web_search_request = false
# 启用统一执行工具（实验性）
unified_exec = false
# 启用 Shell 快照功能
shell_snapshot = false
# 启用自由格式补丁应用（实验性）
apply_patch_freeform = false
# 启用执行策略功能
exec_policy = true
# 启用实验性 Windows 沙箱
experimental_windows_sandbox = false
# 启用需要管理员权限的 Windows 沙箱
elevated_windows_sandbox = false
# 启用远程压缩
remote_compaction = true
# 启用远程模型
remote_models = false
# 为 PowerShell 启用 UTF-8 编码支持
powershell_utf8 = true
# 启用 TUI2 界面（实验性）
tui2 = false
# 在此表下定义 MCP 服务器。留空则禁用。
[mcp_servers]
# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]
# enabled = true # 可选；默认 true
# command = "docs-server" # 必填：启动服务器的命令
# args = ["--port", "4000"] # 可选：命令行参数
# env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value
# env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量
# cwd = "/path/to/server" # 可选：工作目录覆盖
# startup_timeout_sec = 10.0 # 可选；默认 10.0 秒，启动超时
# # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名
# tool_timeout_sec = 60.0 # 可选；默认 60.0 秒，工具调用超时
# enabled_tools = ["search", "summarize"] # 可选：允许列表，只启用指定工具
# disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效）
# --- 示例：可流式 HTTP 传输 ---
# [mcp_servers.github]
# enabled = true # 可选；默认 true
# url = "https://github-mcp.example.com/mcp " # 必填：MCP 服务器 URL
# bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" } # 可选：静态请求头
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头
# startup_timeout_sec = 10.0 # 可选
# tool_timeout_sec = 60.0 # 可选
# enabled_tools = ["list_issues"] # 可选：允许列表
# 模型提供方（扩展/覆盖内置）
# 内置包括：
# - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY）
# - oss（Chat Completions API；默认指向 http://localhost:11434/v1）
[model_providers]
# --- 示例：用显式 base URL 或 headers 覆盖 OpenAI ---
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1 " # 未设置时的默认值
# wire_api = "responses" # "responses" | "chat"（默认因情况而异）
# # requires_openai_auth = true # 内置 OpenAI 默认 true
# # request_max_retries = 4 # 默认 4；最大 100
# # stream_max_retries = 5 # 默认 5；最大 100
# # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟）
# # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure（根据端点选择 Chat/Responses）---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai "
# wire_api = "responses" # 或按端点使用 "chat"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY"
# --- 示例：本地 OSS（例如 Ollama 兼容）---
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"
# Profiles（命名预设）
[profiles]
# 定义配置文件预设，可快速切换不同配置组合
# [profiles.default]
# model = "gpt-5.2-codex"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# oss_provider = "ollama"
# model_reasoning_effort = "medium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/ "
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_unified_exec_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# features = { unified_exec = false }
# Projects（信任级别）
# 将特定 worktree 标记为可信或不可信。
# 为不同项目设置不同的信任级别
[projects]
# 项目路径设置示例
# [projects."/absolute/path/to/project"]
# trust_level = "trusted" # 或 "untrusted"
# OpenTelemetry（OTEL）- 默认禁用
# 可观测性配置，用于监控和调试
[otel]
# 在日志中包含用户提示文本。默认：false（出于隐私考虑）
log_user_prompt = false
# 应用于遥测数据的环境标签。默认："dev"
environment = "dev"
# 导出器：none（默认） | otlp-http | otlp-grpc
# 设置为 none 则禁用遥测导出
exporter = "none"
# Trace 导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"
# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs " # OTLP 接收端点
# protocol = "binary" # "binary" | "json"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}" # 从环境变量读取 API 密钥
# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317 "
# headers = { "x-otlp-meta" = "abc123" }
# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs "
# protocol = "binary"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem" # CA 证书路径
# client-certificate = "/etc/codex/certs/client.pem" # 客户端证书
# client-private-key = "/etc/codex/certs/client-key.pem" # 客户端私钥
config.toml.txt (20.8 KB)
工具推荐
cometix/codex --by:哈雷
GitHub - Haleclipse/codex: Lightweight coding agent that runs in your...
Lightweight coding agent that runs in your terminal
# 卸载原版 Codex 相关组件（如有）
npm uninstall -g @openai/codex
# 安装哈雷版Codex（推荐）
npm install -g @cometix/codex --registry https://registry.npmjs.org
# 验证安装
codex --version
MCP推荐：
windows版：
# Chrome开发者工具
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60000
# Context7向量搜索
[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
startup_timeout_ms = 20000
# Replicate AI模型
[mcp_servers.replicate]
command = "cmd"
args = ["/c", "npx", "-y", "replicate-flux-mcp"]
env = {
SystemRoot="C:\\Windows",
PROGRAMFILES="C:\\Program Files",
REPLICATE_API_TOKEN="YOUR_TOKEN"
}
# GitHub Copilot
[mcp_servers.github]
command = "cmd"
args = [
"/c", "npx", "-y", "mcp-remote@latest",
"https://api.githubcopilot.com/mcp/",
"--header", "Authorization: Bearer YOUR_TOKEN"
]
MacOS版：
# 浏览器开发者工具
[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
# 时序思维助手
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
# 自动化测试工具
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# 时间管理
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
# 任务管理器
[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = {
DATA_DIR = "~/tools/mcp-shrimp-task-manager/data",
TEMPLATES_USE = "zh",
ENABLE_GUI = "false"
}
# 深度维基搜索
[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]
# 桌面控制
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
Skills
Codex-cli操控Gemini-cli的skills:
collaborating-with-gemini-cli-main.zip (14.7 KB)
Codex-cli操控Claude-code的skills
collaborating-with-claude-code-main.zip (15.9 KB)
openspec的skills
---
name: openspec
description: OpenSpec 中文版规范助手 - 规范驱动的 AI 编程开发，帮助初始化、创建提案、编写规格、校验格式并归档变更。触发条件： 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用。
trigger: 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用
---
# OpenSpec 中文版规范助手
OpenSpec 是一个 CLI 工具，通过**规范驱动的开发流程**帮助开发者与 AI 编码助手建立明确的需求共识。核心理念是：**在编写代码前，先将需求文档化并达成一致**，从而消除 AI 工具仅依赖对话历史产生的不可预测输出。
## 什么是 OpenSpec
### 核心价值
- **准确性**：需求明确后大幅减少返工，避免 AI 理解偏差
- **可追溯性**：每个技术决策都有完整的文档记录
- **文档化**：自动生成的规范与代码保持同步，形成活文档
- **团队友好**：清晰的提案便于多人协作和 Code Review
### 适用场景
✅ **最适合**：
- 改进现有项目（1→n 开发，棕地项目）
- 需要高质量实现的关键功能
- 团队协作开发
- 使用 Claude Code、Cursor、Cline 等 AI 工具
- 需要长期维护的项目
❌ **不适合**：
- 快速原型验证（0→1 探索阶段）
- 一次性小脚本
- 需求极度不明确的创新性探索
### 实践价值
前期多花 10-15 分钟与 AI 澄清需求、编写规范，能节省数小时的返工时间。规范文档会随着项目演进不断积累，最终形成完整的系统文档。
## 双文件夹模型
OpenSpec 使用独特的**双文件夹模型**，将"事实"与"提案"分离：
```plain
openspec/
├── specs/ # 📚 事实：已实施并归档的规范（source-of-truth）
│ ├── auth.md
│ ├── api.md
│ └── database.md
└── changes/ # 💡 提案：待实施的变更（明确的差异管理）
├── add-oauth-login/
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
│ └── auth-delta.md
└── optimize-api-cache/
├── proposal.md
└── specs/
└── api-delta.md
```
**设计理念**：
- `specs/` 是系统的当前状态
- `changes/` 是即将到来的变化
- 这种分离让"差异明确且可管理"，特别适合修改现有系统
## 环境与安装
### 基本要求
- **Node.js** >= 20.19.0（Node 22 也兼容）
- **无需 API 密钥**：完全本地执行，与现有开发工具集成
### 安装方式
**全局安装（推荐）**：
```bash
npm install -g @org-hex/openspec-chinese@latest
# 或使用 pnpm
pnpm install -g @org-hex/openspec-chinese@latest
```
**临时使用**（不安装）：
```bash
pnpm dlx @org-hex/openspec-chinese init
pnpm dlx @org-hex/openspec-chinese proposal "功能描述"
```
**验证安装**：
```bash
openspec-chinese --version
openspec-chinese --help
```
### 支持的 AI 工具
OpenSpec 支持 **20+ AI 编程助手**，包括：
- **原生斜杠命令**：Claude Code, Cursor, CodeBuddy, Cline 等
- **AGENTS.md 回退**：所有支持自定义指令的工具（通用兼容）
无需额外配置，安装后即可在所有支持的工具中使用。
## 项目初始化
### 初始化结构
```bash
# 在全新项目中初始化
openspec-chinese init
# 在现有 OpenSpec 项目中切换到中文版
openspec-chinese update
```
生成的完整结构：
```plain
openspec/
├── project.md # 项目上下文（技术栈、架构、团队约定）
├── AGENTS.md # AI 助手通用指令（20+ 工具兼容）
├── specs/ # 现行规范库（已归档的事实）
├── changes/ # 变更提案目录
└── templates/ # 自定义模板（可选）
```
**重要**：初始化后如果 IDE 里斜杠命令未出现，请重启 IDE/AI 工具。
### 补全 project.md
生成 `project.md` 后，应立即向 AI 提出：
```markdown
请阅读 openspec/project.md 并帮助我填写：
1. 项目的核心技术栈
2. 架构设计约定
3. 编码规范和最佳实践
4. 团队协作流程
```
完善的 `project.md` 能让 AI 助手更好地理解项目上下文，生成更符合实际的规范文档。
## 五阶段完整工作流程
### 阶段 1：起草提案（Draft Proposal）
**目标**：创建变更文件夹，初步定义需求
```bash
# 命令行方式
openspec-chinese proposal "添加 OAuth 登录功能"
# AI 工具斜杠命令
/openspec-proposal
```
**输出**：
```plain
openspec/changes/add-oauth-login/
├── proposal.md # AI 生成的初步提案
├── tasks.md # 任务分解清单
└── specs/ # 增量规范（空）
```
**交互要点**：
- AI 会提出澄清问题（例如："使用哪些 OAuth 提供商？"）
- 回答问题后，AI 生成详细的 `proposal.md` 和 `tasks.md`
### 阶段 2：审查对齐（Review & Align）
**目标**：人和 AI 共同审查，反复迭代直到需求明确
```bash
# 查看提案详情
openspec-chinese show add-oauth-login
# 在 AI 工具中交互
"请根据我的反馈修改 proposal.md：
1. 只支持 GitHub 和 Google OAuth
2. 需要处理现有用户的账号合并逻辑
3. 增加 OAuth 失败时的降级方案"
```
**迭代过程**：
1. 审查 `proposal.md` 的 Why/What/Impact
2. 检查 `tasks.md` 的任务拆解是否合理
3. 提出修改建议，让 AI 更新文档
4. 重复直到完全对齐
**关键**：这个阶段多花时间，后续实施会快很多。
### 阶段 3：编写规格（Write Specs）
**目标**：在 `specs/` 目录下编写符合格式的增量规范
```bash
# AI 工具中请求
"请为 add-oauth-login 变更编写规格文档，放在 specs/ 目录"
```
**规范格式**（详见下文"规格文档格式要求"）：
```markdown
## ADDED Requirements
### Requirement: OAuth 登录支持
系统 MUST 支持通过 GitHub 和 Google 进行 OAuth 登录。
#### Scenario: GitHub OAuth 登录成功
- **WHEN** 用户点击"使用 GitHub 登录"按钮
- **THEN** 系统跳转到 GitHub OAuth 授权页面
- **AND** 授权成功后返回并创建会话
```
### 阶段 4：校验与实施（Validate & Implement）
**校验格式**：
```bash
# 严格格式校验
openspec-chinese validate add-oauth-login --strict
# 中文格式专项校验（需配置）
npm run validate:chinese
```
**实施开发**：
```bash
# AI 工具中参考规范实施
"请参考 openspec/changes/add-oauth-login/specs/ 中的规范，
按照 tasks.md 的任务清单逐步实施功能"
```
**任务追踪**：
- 在 `tasks.md` 中勾选已完成的任务
- AI 会自动参考规范，减少理解偏差
### 阶段 5：归档与文档化（Archive & Document）
**目标**：将完成的变更合并到主规范库
```bash
# 查看所有变更
openspec-chinese list
# 归档已完成的变更
openspec-chinese archive add-oauth-login --yes
```
**效果**：
- `changes/add-oauth-login/` 的规范合并到 `specs/`
- 变更记录自动保存
- 形成活文档，与代码同步
### 流程图总览
```mermaid
flowchart TD
A[1. 起草提案<br/>AI 澄清问题] --> B[2. 审查对齐<br/>迭代完善需求]
B --> C[3. 编写规格<br/>Delta + Scenarios]
C --> D[4. 校验格式<br/>validate --strict]
D --> E{格式正确?}
E -- 否 --> C
E -- 是 --> F[5. 实施开发<br/>按规范编码]
F --> G[6. 归档文档<br/>archive --yes]
G --> H[规范库更新<br/>活文档形成]
```
## 规格文档格式要求
OpenSpec 使用**严格的格式规范**，确保 AI 和人都能准确理解需求。
### 核心原则
1. **Delta 分区**：使用英文标题标识变更类型
2. **强制关键词**：需求必须包含 MUST/SHALL/SHOULD
3. **Gherkin 场景**：使用英文关键字描述验收标准
4. **中英混合**：结构英文，描述中文
### 1. Delta 分区（必填）
**三种变更类型**：
```markdown
## ADDED Requirements
# 新增的能力
## MODIFIED Requirements
# 修改现有行为
## REMOVED Requirements
# 废弃的功能（需说明原因和迁移路径）
```
### 2. Requirement 语句规范
**格式**：
```markdown
### Requirement: [需求名称]
系统 [MUST/SHALL/SHOULD] [能力描述]。
```
**强制关键词**：
- **MUST** / **SHALL**：强制要求，不可妥协
- **SHOULD**：建议要求，可协商
- **MAY**：可选要求
**示例**：
```markdown
### Requirement: 用户搜索功能
系统 MUST 提供用户搜索功能，支持按用户名、邮箱、手机号进行模糊查询。
系统 SHOULD 在搜索结果中高亮匹配的关键词。
```
### 3. Scenario 场景描述（验收标准）
**格式**：
```markdown
#### Scenario: [场景名称]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件/结果]
```
**要求**：
- 每个 Requirement 至少有一个 Scenario
- 使用**英文 Gherkin 关键字**（WHEN/THEN/AND/GIVEN）
- 描述内容可以是中文
**示例**：
```markdown
#### Scenario: 按邮箱搜索用户
- **WHEN** 用户在搜索框输入 "test@example.com"
- **THEN** 系统返回邮箱包含该字符串的用户列表
- **AND** 列表按相关度排序
- **AND** 邮箱中的匹配部分高亮显示
#### Scenario: 搜索无结果
- **WHEN** 用户输入不存在的邮箱
- **THEN** 系统显示"未找到匹配用户"
- **AND** 提示用户检查输入或尝试其他搜索条件
```
### 4. 删除需求的特殊要求
删除需求时**必须**提供 Reason 和 Migration：
```markdown
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重的安全隐患，违反 OWASP 安全规范
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密存储
2. 用户首次登录时会自动升级密码加密方式
3. 详细迁移指南：`docs/password-migration.md`
```
### 5. 修改需求的说明
修改现有功能时应说明变化：
```markdown
## MODIFIED Requirements
### Requirement: 用户列表分页
- **变化说明**: 将每页默认显示数量从 20 条调整为 50 条
- **原因**: 用户反馈每页 20 条过少，频繁翻页影响体验
- **影响范围**:
- 前端分页组件
- 后端 API 默认参数
- 性能测试基准需重新评估
#### Scenario: 默认分页数量
- **WHEN** 用户访问用户列表页面
- **THEN** 系统默认每页显示 50 条记录
- **AND** 用户可以在设置中自定义每页条数（10/20/50/100）
```
### 6. 完整示例模板
```markdown
## ADDED Requirements
### Requirement: 用户数据导出功能
系统 MUST 提供用户数据导出功能，支持 CSV 和 JSON 两种格式。
#### Scenario: 导出为 CSV 格式
- **WHEN** 管理员点击"导出为 CSV"按钮
- **THEN** 系统生成包含所有用户数据的 CSV 文件
- **AND** 文件包含字段：用户名、邮箱、注册时间、最后登录时间、状态
- **AND** 文件名格式为 `users_export_YYYYMMDD_HHmmss.csv`
#### Scenario: 导出权限检查
- **WHEN** 非管理员用户尝试导出
- **THEN** 系统返回 403 Forbidden 错误
- **AND** 前端显示"权限不足"提示
#### Scenario: 大数据量导出
- **GIVEN** 系统有超过 10000 条用户记录
- **WHEN** 管理员点击导出
- **THEN** 系统显示"正在生成导出文件"进度提示
- **AND** 导出任务在后台异步执行
- **AND** 完成后通过邮件发送下载链接
## MODIFIED Requirements
### Requirement: 用户列表查询性能
- **变化说明**: 为用户表添加邮箱和手机号索引
- **原因**: 当前搜索性能在 10 万用户以上明显下降
- **预期效果**: 搜索响应时间从 2-3 秒降低到 < 500ms
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重安全隐患，必须移除
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密（cost=10）
2. 用户下次登录时自动完成迁移
3. 详细文档：`docs/security/password-migration.md`
```
## 常用命令速查
### 项目管理
```bash
# 初始化全新项目
openspec-chinese init
# 更新/切换到中文版
openspec-chinese update
# 查看版本
openspec-chinese --version
```
### 变更管理
```bash
# 创建新提案
openspec-chinese proposal "功能描述"
# 查看所有变更
openspec-chinese list
# 查看特定变更详情
openspec-chinese show <change-name>
# 校验格式（严格模式）
openspec-chinese validate <change-name> --strict
# 归档已完成的变更
openspec-chinese archive <change-name> --yes
```
### AI 工具斜杠命令
在支持的 AI 工具（Claude Code, Cursor 等）中：
```bash
/openspec-proposal # 创建新提案
/openspec-validate # 校验当前变更
/openspec-archive # 归档变更
```
## 自定义模板
### 创建模板
在 `openspec/templates/` 目录下创建自定义模板：
```bash
# 创建功能规格模板
openspec/templates/feature-spec.md
# 创建 API 规格模板
openspec/templates/api-spec.md
# 创建数据库变更模板
openspec/templates/db-migration-spec.md
```
### 模板示例
```markdown
<!-- openspec/templates/feature-spec.md -->
## ADDED Requirements
### Requirement: [功能名称]
系统 MUST [功能描述]。
#### Scenario: [主要场景]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件]
#### Scenario: [错误场景]
- **WHEN** [异常情况]
- **THEN** [错误处理]
- **AND** [用户提示]
## MODIFIED Requirements
（如有修改现有功能，在此说明）
## REMOVED Requirements
（如有废弃功能，在此说明原因和迁移路径）
```
### 使用模板
```bash
# 创建新变更时，从模板复制
cp openspec/templates/feature-spec.md openspec/changes/new-feature/specs/feature.md
# 然后填充具体内容
```
## 最佳实践
### 1. 提案阶段多花时间
- ✅ 与 AI 充分沟通，澄清所有疑问
- ✅ 详细拆解任务到可执行的粒度
- ✅ 确保 proposal.md 中的 Why/What/Impact 清晰
- ❌ 不要急于开始编码，需求不明会导致大量返工
### 2. 规格要具体可验证
- ✅ 每个需求至少有 1-2 个 Scenario
- ✅ Scenario 要具体，可直接转化为测试用例
- ✅ 包含正常流程和异常流程
- ❌ 避免模糊描述，如"系统应该快速响应"
### 3. 利用 validate 命令
```bash
# 每次编辑规格后立即校验
openspec-chinese validate <change> --strict
# 配置 Git pre-commit hook
npm run validate:chinese
```
### 4. 保持规范与代码同步
- ✅ 代码实现后，确保规范准确反映最终结果
- ✅ 如有偏差，更新规范或代码使其一致
- ✅ 归档前再次审查规范的准确性
### 5. 利用 project.md
```markdown
<!-- openspec/project.md -->
# 项目上下文
## 技术栈
- 前端: React 18 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL 14
## 架构约定
- RESTful API 设计
- JWT 认证
- 统一错误处理中间件
## 编码规范
- ESLint + Prettier
- 函数式组件优先
- 使用 React Query 管理服务端状态
```
完善的 `project.md` 能让 AI 生成更符合项目规范的代码。
### 6. 版本兼容
OpenSpec 中文版与英文版**完全兼容**：
```bash
# 切换到中文版
openspec-chinese update
# 切换回英文版
openspec update
```
两个版本可以在团队中并存，规范文件格式完全一致。
## 常见问题排查
### 命令不可用
**症状**：`openspec-chinese: command not found`
**解决方案**：
```bash
# 检查是否在 PATH 中
which openspec-chinese # Mac/Linux
where openspec-chinese # Windows
# 检查 npm 全局 bin 路径
npm config get prefix
# 重新安装
npm uninstall -g @org-hex/openspec-chinese
npm install -g @org-hex/openspec-chinese@latest
```
### 斜杠命令未出现
**症状**：AI 工具中看不到 `/openspec-*` 命令
**解决方案**：
```bash
# 执行更新命令
openspec-chinese update
# 重启 IDE/AI 工具
# 检查是否生成了 AGENTS.md
ls openspec/AGENTS.md
```
### 校验报错
**常见错误**：
1. **缺少 Delta 分区**
```plain
Error: Missing required Delta sections (ADDED/MODIFIED/REMOVED)
```
解决：确保至少有一个 Delta 分区
2. **缺少 MUST/SHALL 关键词**
```plain
Error: Requirement missing mandatory keywords
```
解决：在需求描述中添加 MUST/SHALL/SHOULD
3. **Scenario 层级错误**
```plain
Error: Scenario must be under a Requirement
```
解决：确保 `#### Scenario:` 在 `### Requirement:` 之下
4. **Gherkin 关键字使用中文**
```plain
Error: Gherkin keywords must be in English
```
解决：使用 WHEN/THEN/AND 而非"当/那么/并且"
### 归档失败
**症状**：`openspec-chinese archive` 报错
**可能原因**：
- 变更未通过校验
- specs/ 目录为空
- Git 冲突
**解决方案**：
```bash
# 先校验格式
openspec-chinese validate <change> --strict
# 检查 specs/ 目录
ls openspec/changes/<change>/specs/
# 解决 Git 冲突后重试
git status
```
## 触发场景
本技能应在以下场景**主动调用**：
### 明确触发
1. 用户提及 "openspec"
2. 用户提及 "规范文档"、"需求文档"
3. 用户提及 "spec-driven development"
4. 用户询问如何管理需求
### 上下文触发
6. 用户开始新功能开发前（建议使用 OpenSpec）
7. 用户抱怨 AI 理解偏差或频繁返工
8. 用户询问如何让 AI 更准确理解需求
9. 用户需要生成技术文档
### 项目阶段触发
10. 项目初始化阶段（建议配置 OpenSpec）
11. 准备重大重构时（建议先写规范）
12. 团队协作场景（提供统一的需求描述）
## 执行长任务时的注意事项
1. **及时更新任务文件**：
> **必须要**及时更新对应任务的 `tasks.md` 任务进度文件。避免出现大批量完成任务后，没有更新进度文件的情况，带来严重的误解。
2. 启动**多个子代理**分模块并行完成任务：
> 务必要启动多个在后台运行的子代理，同时完成 openspec 设定的一系列繁杂的任务。以便加快速度。你应该至少同时启用至少 4 个子代理。并根据情况，主动增加足够数量的子代理完成任务。
3. 回复文本语言：
> 务必用**中文**回复用户。
4. 上下文合并后重新阅读一次任务要求：
> 为了避免你在自动合并上下文的时候，给后续的任务带来明显的幻觉，你应该及时的重新阅读 openspec 的任务规范要求。
5. 连续的，持续的执行长任务：
- 你应该一次性完成 `tasks.md` 所记录的全部任务。你应该同时新建多个子代理，做出合理的任务划分，一次性完成任务。
- 不要在完成一个任务的时候就停下来询问用户。这种停顿方式很低效率，你要避免这种执行方式。
6. **禁止**编写脚本完成批处理任务：
- **不允许**你编写任何 Python、typescript、javascript，或 bash 脚本，完成大批量代码删改之类的任务。
- 你应该阅读文件来完成更改，而不是使用不稳定的，容易带来语法错误的，删改不干净不合理的批处理脚本，来完成任务。
- 你应该新建多个子代理，用具体的子代理来完成大规模的修改任务。
7. 主从代理的调度设计：
- `主代理的职责`： 主代理应该负责全面的，完整的阅读来自 openspec 目录下全部的 markdown 文档任务要求。并按照模块和错误类型，新建足够数量的子代理。并持续监听，定期收集来自子代理的处理反馈。
- `子代理的职责`： 子代理应该严格按照主代理给定的要求来完成任务。
8. 什么情况下应该新建子代理？在以下的几种情况下，主代理应该及时新建子代理来完成任务：
- 大规模的代码探索与信息收集任务。
- 访问 url 获取文档信息的任务。
- 指定严格顺序的代码修改任务。
- 报告编写任务。
- 进度文件更新与编写任务。
## 注意事项
### 格式要求（严格遵守）
1. ✅ Delta 分区标题必须使用**英文**（ADDED/MODIFIED/REMOVED）
2. ✅ Gherkin 关键字必须使用**英文**（WHEN/THEN/AND/GIVEN）
3. ✅ 需求描述中必须包含 MUST/SHALL/SHOULD 等**强制关键词**
4. ✅ 删除需求时必须提供 **Reason** 和 **Migration**
5. ✅ 每个 Requirement 至少有**一个 Scenario**
### 工作流建议
1. ⏰ 提案阶段多花时间，实施阶段会快很多
2. 📝 规格要具体可验证，能直接转化为测试用例
3. ✅ 每次编辑后立即运行 `validate --strict`
4. 🔄 保持规范与代码同步，归档前再次审查
5. 📚 善用 `project.md` 提供项目上下文
### 团队协作
1. 👥 规范文件适合 Code Review
2. 📖 `changes/` 目录中的提案可作为 PR 描述
3. 🔍 归档后的 `specs/` 成为团队共识
4. 🌍 中英文版本可并存，格式完全兼容
### 工具集成
1. 🤖 支持 20+ AI 编程工具，无缝集成
2. 🔒 完全本地执行，无需 API 密钥
3. 📂 AGENTS.md 提供通用兼容性
4. ⚡ 斜杠命令提供快捷操作
---
## 参考资源
- **OpenSpec 中文版仓库**: https://github.com/hex-novaflow-ai/OpenSpec-Chinese
- **OpenSpec 原版仓库**: https://github.com/Fission-AI/OpenSpec
- **介绍教程**: https://www.aivi.fyi/llms/introduce-OpenSpec
- **官方文档**: 项目 README 和 docs 目录
全局agents.md推荐：
AGENTS.md.txt (18.9 KB)
网友解答：config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
--【壹】--： # 抑制内部推理事件的输出。默认：false # 设置为 true 可隐藏模型的推理过程 hide_agent_reasoning = false # 当可用时显示原始推理内容。默认：false # 显示模型未格式化的原始推理文本 show_raw_agent_reasoning = false # 禁用 TUI 中的"突发粘贴（burst-paste）"检测。默认：false # 当快速粘贴大量内容时，Codex 会检测并提示确认，此选项可禁用该功能 disable_paste_burst = false # 记录 Windows 入门设置确认（仅 Windows）。默认：false # 标记 WSL 设置向导是否已确认 windows_wsl_setup_acknowledged = false # 启动时检查更新。默认：true # 控制 Codex 启动时是否检查新版本 check_for_update_on_startup = true
--【贰】--： # 在此表下定义 MCP 服务器。留空则禁用。
--【叁】--： # Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。 # 支持 gpt-5.2-codex, gpt-5.2, o1-pro-codex 等 model = "gpt-5.2-codex" # /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。 # 可设置为不同的模型以优化代码审查效果 review_model = "gpt-5.2-codex" # 从 [model_providers] 中选择的提供方 id。默认："openai"。 # 可选值：openai, azure, ollama 等，需在 [model_providers] 部分定义 model_provider = "openai" # 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。 # 设置为 ollama 等支持开源模型的提供方 # oss_provider = "ollama" # 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。 # 取消注释以强制指定这些值。 # 模型的上下文窗口大小（token 数），影响单次请求可处理的最大代码量 # model_context_window = 128000 # token 数；默认：按模型自动决定 # 自动触发历史压缩的 token 阈值，0 表示使用模型默认值 # model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值 # 每个工具输出存储的最大 token 数，防止工具输出占用过多上下文 # tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
--【肆】--： # Profiles（命名预设）
--【伍】--： # 实验性开关（旧版；优先使用 [features]）
--【陆】--：
感谢！！
--【柒】--：
agents.md,我建议项目中使用 codex 自己生成。全局我推荐站内一个大佬的
--【捌】--： # 何时请求命令审批： # - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认 # - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权 # - on-request：由模型决定何时询问（默认） # - never：从不询问（风险较大） approval_policy = "on-request" # 工具调用的文件系统/网络沙箱策略： # - read-only（默认）：只允许读取文件，最安全 # - workspace-write：允许在工作区写入文件 # - danger-full-access（无沙箱；极其危险）：允许任意文件操作和网络访问 sandbox_mode = "read-only"
--【玖】--：
减少推理摘要能省钱吗？
model_reasoning_summary = “concise”
--【拾】--： # 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768 # 限制 AGENTS.md 文件的大小，防止占用过多上下文 project_doc_max_bytes = 32768 # 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[] # 例如：[".codex", "PROJECT.md"]，会在找不到 AGENTS.md 时尝试这些文件 project_doc_fallback_filenames = [] # 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"] # 当向上遍历目录树时，遇到这些文件/文件夹就认为是项目根 # project_root_markers = [".git"]
--【拾壹】--：
已下载！
--【拾贰】--： # 模型提供方（扩展/覆盖内置）
--【拾叁】--：
学习了。
--【拾肆】--： # 历史与文件打开方式
--【拾伍】--： # 审批与沙箱
--【拾陆】--： # 生成子进程的 Shell 环境策略（表）
--【拾柒】--： # 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh） # 更高的推理强度会让模型思考更充分，但响应时间更长 model_reasoning_effort = "medium" # 推理摘要：auto | concise | detailed | none（默认：auto） # 控制是否显示模型的推理过程摘要 model_reasoning_summary = "auto" # GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium） # 影响模型回复的详细程度 model_verbosity = "medium" # 为当前模型强制启用推理摘要（默认：false） # 即使模型默认不支持，也尝试启用推理摘要 model_supports_reasoning_summaries = false
--【拾捌】--： # 当前启用的 profile 名称。未设置时，不应用任何 profile。 # 可设置为 [profiles] 部分定义的预设名称，如 "default" # profile = "default"
--【拾玖】--：
感谢佬友分享，这就试试
--【贰拾】--：
这俩配置文件有什么区别吗，没改过config.toml
【21】
我在用这个，感觉还行
https://linux.do/t/topic/1423040
【22】 # 历史（表）
【23】 # 外部通知程序（argv 数组）。未设置时：禁用。 # 配置系统通知，例如使用 notify-send 在 Linux 上显示桌面通知 # 示例：notify = ["notify-send", "Codex"] notify = [ ]
【24】 [features] # 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。 # 启用 Shell 工具，允许执行命令 shell_tool = true # 启用网页搜索请求功能 web_search_request = false # 启用统一执行工具（实验性） unified_exec = false # 启用 Shell 快照功能 shell_snapshot = false # 启用自由格式补丁应用（实验性） apply_patch_freeform = false # 启用执行策略功能 exec_policy = true # 启用实验性 Windows 沙箱 experimental_windows_sandbox = false # 启用需要管理员权限的 Windows 沙箱 elevated_windows_sandbox = false # 启用远程压缩 remote_compaction = true # 启用远程模型 remote_models = false # 为 PowerShell 启用 UTF-8 编码支持 powershell_utf8 = true # 启用 TUI2 界面（实验性） tui2 = false
【25】 # 通知
【26】 大帅笔:
全局我推荐站内一个大佬的
求推荐。
【27】 #### # Profiles（命名预设）
【28】 # 沙箱设置（表）
【29】 # 在不删除技能的情况下禁用或重新启用某个技能。 [[skills.config]] # 技能文件的路径 # path = "/path/to/skill" # 是否启用该技能，false 可临时禁用而不删除配置 # enabled = false
【30】 # 可观测性配置，用于监控和调试 [otel] # 在日志中包含用户提示文本。默认：false（出于隐私考虑） log_user_prompt = false # 应用于遥测数据的环境标签。默认："dev" environment = "dev" # 导出器：none（默认） | otlp-http | otlp-grpc # 设置为 none 则禁用遥测导出 exporter = "none" # Trace 导出器：none（默认） | otlp-http | otlp-grpc trace_exporter = "none" # 示例：OTLP/HTTP 导出器配置 # [otel.exporter."otlp-http"] # endpoint = "https://otel.example.com/v1/logs " # OTLP 接收端点 # protocol = "binary" # "binary" | "json" # [otel.exporter."otlp-http".headers] # "x-otlp-api-key" = "${OTLP_TOKEN}" # 从环境变量读取 API 密钥 # 示例：OTLP/gRPC 导出器配置 # [otel.exporter."otlp-grpc"] # endpoint = "https://otel.example.com:4317 " # headers = { "x-otlp-meta" = "abc123" } # 示例：带双向 TLS 的 OTLP 导出器 # [otel.exporter."otlp-http"] # endpoint = "https://otel.example.com/v1/logs " # protocol = "binary" # [otel.exporter."otlp-http".headers] # "x-otlp-api-key" = "${OTLP_TOKEN}" # [otel.exporter."otlp-http".tls] # ca-certificate = "certs/otel-ca.pem" # CA 证书路径 # client-certificate = "/etc/codex/certs/client.pem" # 客户端证书 # client-private-key = "/etc/codex/certs/client-key.pem" # 客户端私钥
config.toml.txt (20.8 KB)
工具推荐
cometix/codex --by:哈雷
GitHub - Haleclipse/codex: Lightweight coding agent that runs in your...
Lightweight coding agent that runs in your terminal
# 卸载原版 Codex 相关组件（如有）
npm uninstall -g @openai/codex
# 安装哈雷版Codex（推荐）
npm install -g @cometix/codex --registry https://registry.npmjs.org
# 验证安装
codex --version
MCP推荐：
windows版：
# Chrome开发者工具
[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 60000
# Context7向量搜索
[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
startup_timeout_ms = 20000
# Replicate AI模型
[mcp_servers.replicate]
command = "cmd"
args = ["/c", "npx", "-y", "replicate-flux-mcp"]
env = {
SystemRoot="C:\\Windows",
PROGRAMFILES="C:\\Program Files",
REPLICATE_API_TOKEN="YOUR_TOKEN"
}
# GitHub Copilot
[mcp_servers.github]
command = "cmd"
args = [
"/c", "npx", "-y", "mcp-remote@latest",
"https://api.githubcopilot.com/mcp/",
"--header", "Authorization: Bearer YOUR_TOKEN"
]
MacOS版：
# 浏览器开发者工具
[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]
# 时序思维助手
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
# 自动化测试工具
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# 时间管理
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
# 任务管理器
[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = {
DATA_DIR = "~/tools/mcp-shrimp-task-manager/data",
TEMPLATES_USE = "zh",
ENABLE_GUI = "false"
}
# 深度维基搜索
[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]
# 桌面控制
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
Skills
Codex-cli操控Gemini-cli的skills:
collaborating-with-gemini-cli-main.zip (14.7 KB)
Codex-cli操控Claude-code的skills
collaborating-with-claude-code-main.zip (15.9 KB)
openspec的skills
---
name: openspec
description: OpenSpec 中文版规范助手 - 规范驱动的 AI 编程开发，帮助初始化、创建提案、编写规格、校验格式并归档变更。触发条件： 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用。
trigger: 当用户提及 openspec、规范文档、需求管理、变更提案、spec-driven development 等关键词时主动调用
---
# OpenSpec 中文版规范助手
OpenSpec 是一个 CLI 工具，通过**规范驱动的开发流程**帮助开发者与 AI 编码助手建立明确的需求共识。核心理念是：**在编写代码前，先将需求文档化并达成一致**，从而消除 AI 工具仅依赖对话历史产生的不可预测输出。
## 什么是 OpenSpec
### 核心价值
- **准确性**：需求明确后大幅减少返工，避免 AI 理解偏差
- **可追溯性**：每个技术决策都有完整的文档记录
- **文档化**：自动生成的规范与代码保持同步，形成活文档
- **团队友好**：清晰的提案便于多人协作和 Code Review
### 适用场景
✅ **最适合**：
- 改进现有项目（1→n 开发，棕地项目）
- 需要高质量实现的关键功能
- 团队协作开发
- 使用 Claude Code、Cursor、Cline 等 AI 工具
- 需要长期维护的项目
❌ **不适合**：
- 快速原型验证（0→1 探索阶段）
- 一次性小脚本
- 需求极度不明确的创新性探索
### 实践价值
前期多花 10-15 分钟与 AI 澄清需求、编写规范，能节省数小时的返工时间。规范文档会随着项目演进不断积累，最终形成完整的系统文档。
## 双文件夹模型
OpenSpec 使用独特的**双文件夹模型**，将"事实"与"提案"分离：
```plain
openspec/
├── specs/ # 📚 事实：已实施并归档的规范（source-of-truth）
│ ├── auth.md
│ ├── api.md
│ └── database.md
└── changes/ # 💡 提案：待实施的变更（明确的差异管理）
├── add-oauth-login/
│ ├── proposal.md
│ ├── tasks.md
│ └── specs/
│ └── auth-delta.md
└── optimize-api-cache/
├── proposal.md
└── specs/
└── api-delta.md
```
**设计理念**：
- `specs/` 是系统的当前状态
- `changes/` 是即将到来的变化
- 这种分离让"差异明确且可管理"，特别适合修改现有系统
## 环境与安装
### 基本要求
- **Node.js** >= 20.19.0（Node 22 也兼容）
- **无需 API 密钥**：完全本地执行，与现有开发工具集成
### 安装方式
**全局安装（推荐）**：
```bash
npm install -g @org-hex/openspec-chinese@latest
# 或使用 pnpm
pnpm install -g @org-hex/openspec-chinese@latest
```
**临时使用**（不安装）：
```bash
pnpm dlx @org-hex/openspec-chinese init
pnpm dlx @org-hex/openspec-chinese proposal "功能描述"
```
**验证安装**：
```bash
openspec-chinese --version
openspec-chinese --help
```
### 支持的 AI 工具
OpenSpec 支持 **20+ AI 编程助手**，包括：
- **原生斜杠命令**：Claude Code, Cursor, CodeBuddy, Cline 等
- **AGENTS.md 回退**：所有支持自定义指令的工具（通用兼容）
无需额外配置，安装后即可在所有支持的工具中使用。
## 项目初始化
### 初始化结构
```bash
# 在全新项目中初始化
openspec-chinese init
# 在现有 OpenSpec 项目中切换到中文版
openspec-chinese update
```
生成的完整结构：
```plain
openspec/
├── project.md # 项目上下文（技术栈、架构、团队约定）
├── AGENTS.md # AI 助手通用指令（20+ 工具兼容）
├── specs/ # 现行规范库（已归档的事实）
├── changes/ # 变更提案目录
└── templates/ # 自定义模板（可选）
```
**重要**：初始化后如果 IDE 里斜杠命令未出现，请重启 IDE/AI 工具。
### 补全 project.md
生成 `project.md` 后，应立即向 AI 提出：
```markdown
请阅读 openspec/project.md 并帮助我填写：
1. 项目的核心技术栈
2. 架构设计约定
3. 编码规范和最佳实践
4. 团队协作流程
```
完善的 `project.md` 能让 AI 助手更好地理解项目上下文，生成更符合实际的规范文档。
## 五阶段完整工作流程
### 阶段 1：起草提案（Draft Proposal）
**目标**：创建变更文件夹，初步定义需求
```bash
# 命令行方式
openspec-chinese proposal "添加 OAuth 登录功能"
# AI 工具斜杠命令
/openspec-proposal
```
**输出**：
```plain
openspec/changes/add-oauth-login/
├── proposal.md # AI 生成的初步提案
├── tasks.md # 任务分解清单
└── specs/ # 增量规范（空）
```
**交互要点**：
- AI 会提出澄清问题（例如："使用哪些 OAuth 提供商？"）
- 回答问题后，AI 生成详细的 `proposal.md` 和 `tasks.md`
### 阶段 2：审查对齐（Review & Align）
**目标**：人和 AI 共同审查，反复迭代直到需求明确
```bash
# 查看提案详情
openspec-chinese show add-oauth-login
# 在 AI 工具中交互
"请根据我的反馈修改 proposal.md：
1. 只支持 GitHub 和 Google OAuth
2. 需要处理现有用户的账号合并逻辑
3. 增加 OAuth 失败时的降级方案"
```
**迭代过程**：
1. 审查 `proposal.md` 的 Why/What/Impact
2. 检查 `tasks.md` 的任务拆解是否合理
3. 提出修改建议，让 AI 更新文档
4. 重复直到完全对齐
**关键**：这个阶段多花时间，后续实施会快很多。
### 阶段 3：编写规格（Write Specs）
**目标**：在 `specs/` 目录下编写符合格式的增量规范
```bash
# AI 工具中请求
"请为 add-oauth-login 变更编写规格文档，放在 specs/ 目录"
```
**规范格式**（详见下文"规格文档格式要求"）：
```markdown
## ADDED Requirements
### Requirement: OAuth 登录支持
系统 MUST 支持通过 GitHub 和 Google 进行 OAuth 登录。
#### Scenario: GitHub OAuth 登录成功
- **WHEN** 用户点击"使用 GitHub 登录"按钮
- **THEN** 系统跳转到 GitHub OAuth 授权页面
- **AND** 授权成功后返回并创建会话
```
### 阶段 4：校验与实施（Validate & Implement）
**校验格式**：
```bash
# 严格格式校验
openspec-chinese validate add-oauth-login --strict
# 中文格式专项校验（需配置）
npm run validate:chinese
```
**实施开发**：
```bash
# AI 工具中参考规范实施
"请参考 openspec/changes/add-oauth-login/specs/ 中的规范，
按照 tasks.md 的任务清单逐步实施功能"
```
**任务追踪**：
- 在 `tasks.md` 中勾选已完成的任务
- AI 会自动参考规范，减少理解偏差
### 阶段 5：归档与文档化（Archive & Document）
**目标**：将完成的变更合并到主规范库
```bash
# 查看所有变更
openspec-chinese list
# 归档已完成的变更
openspec-chinese archive add-oauth-login --yes
```
**效果**：
- `changes/add-oauth-login/` 的规范合并到 `specs/`
- 变更记录自动保存
- 形成活文档，与代码同步
### 流程图总览
```mermaid
flowchart TD
A[1. 起草提案<br/>AI 澄清问题] --> B[2. 审查对齐<br/>迭代完善需求]
B --> C[3. 编写规格<br/>Delta + Scenarios]
C --> D[4. 校验格式<br/>validate --strict]
D --> E{格式正确?}
E -- 否 --> C
E -- 是 --> F[5. 实施开发<br/>按规范编码]
F --> G[6. 归档文档<br/>archive --yes]
G --> H[规范库更新<br/>活文档形成]
```
## 规格文档格式要求
OpenSpec 使用**严格的格式规范**，确保 AI 和人都能准确理解需求。
### 核心原则
1. **Delta 分区**：使用英文标题标识变更类型
2. **强制关键词**：需求必须包含 MUST/SHALL/SHOULD
3. **Gherkin 场景**：使用英文关键字描述验收标准
4. **中英混合**：结构英文，描述中文
### 1. Delta 分区（必填）
**三种变更类型**：
```markdown
## ADDED Requirements
# 新增的能力
## MODIFIED Requirements
# 修改现有行为
## REMOVED Requirements
# 废弃的功能（需说明原因和迁移路径）
```
### 2. Requirement 语句规范
**格式**：
```markdown
### Requirement: [需求名称]
系统 [MUST/SHALL/SHOULD] [能力描述]。
```
**强制关键词**：
- **MUST** / **SHALL**：强制要求，不可妥协
- **SHOULD**：建议要求，可协商
- **MAY**：可选要求
**示例**：
```markdown
### Requirement: 用户搜索功能
系统 MUST 提供用户搜索功能，支持按用户名、邮箱、手机号进行模糊查询。
系统 SHOULD 在搜索结果中高亮匹配的关键词。
```
### 3. Scenario 场景描述（验收标准）
**格式**：
```markdown
#### Scenario: [场景名称]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件/结果]
```
**要求**：
- 每个 Requirement 至少有一个 Scenario
- 使用**英文 Gherkin 关键字**（WHEN/THEN/AND/GIVEN）
- 描述内容可以是中文
**示例**：
```markdown
#### Scenario: 按邮箱搜索用户
- **WHEN** 用户在搜索框输入 "test@example.com"
- **THEN** 系统返回邮箱包含该字符串的用户列表
- **AND** 列表按相关度排序
- **AND** 邮箱中的匹配部分高亮显示
#### Scenario: 搜索无结果
- **WHEN** 用户输入不存在的邮箱
- **THEN** 系统显示"未找到匹配用户"
- **AND** 提示用户检查输入或尝试其他搜索条件
```
### 4. 删除需求的特殊要求
删除需求时**必须**提供 Reason 和 Migration：
```markdown
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重的安全隐患，违反 OWASP 安全规范
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密存储
2. 用户首次登录时会自动升级密码加密方式
3. 详细迁移指南：`docs/password-migration.md`
```
### 5. 修改需求的说明
修改现有功能时应说明变化：
```markdown
## MODIFIED Requirements
### Requirement: 用户列表分页
- **变化说明**: 将每页默认显示数量从 20 条调整为 50 条
- **原因**: 用户反馈每页 20 条过少，频繁翻页影响体验
- **影响范围**:
- 前端分页组件
- 后端 API 默认参数
- 性能测试基准需重新评估
#### Scenario: 默认分页数量
- **WHEN** 用户访问用户列表页面
- **THEN** 系统默认每页显示 50 条记录
- **AND** 用户可以在设置中自定义每页条数（10/20/50/100）
```
### 6. 完整示例模板
```markdown
## ADDED Requirements
### Requirement: 用户数据导出功能
系统 MUST 提供用户数据导出功能，支持 CSV 和 JSON 两种格式。
#### Scenario: 导出为 CSV 格式
- **WHEN** 管理员点击"导出为 CSV"按钮
- **THEN** 系统生成包含所有用户数据的 CSV 文件
- **AND** 文件包含字段：用户名、邮箱、注册时间、最后登录时间、状态
- **AND** 文件名格式为 `users_export_YYYYMMDD_HHmmss.csv`
#### Scenario: 导出权限检查
- **WHEN** 非管理员用户尝试导出
- **THEN** 系统返回 403 Forbidden 错误
- **AND** 前端显示"权限不足"提示
#### Scenario: 大数据量导出
- **GIVEN** 系统有超过 10000 条用户记录
- **WHEN** 管理员点击导出
- **THEN** 系统显示"正在生成导出文件"进度提示
- **AND** 导出任务在后台异步执行
- **AND** 完成后通过邮件发送下载链接
## MODIFIED Requirements
### Requirement: 用户列表查询性能
- **变化说明**: 为用户表添加邮箱和手机号索引
- **原因**: 当前搜索性能在 10 万用户以上明显下降
- **预期效果**: 搜索响应时间从 2-3 秒降低到 < 500ms
## REMOVED Requirements
### Requirement: 用户密码明文存储
- **Reason**: 严重安全隐患，必须移除
- **Migration**:
1. 所有密码已迁移到 bcrypt 加密（cost=10）
2. 用户下次登录时自动完成迁移
3. 详细文档：`docs/security/password-migration.md`
```
## 常用命令速查
### 项目管理
```bash
# 初始化全新项目
openspec-chinese init
# 更新/切换到中文版
openspec-chinese update
# 查看版本
openspec-chinese --version
```
### 变更管理
```bash
# 创建新提案
openspec-chinese proposal "功能描述"
# 查看所有变更
openspec-chinese list
# 查看特定变更详情
openspec-chinese show <change-name>
# 校验格式（严格模式）
openspec-chinese validate <change-name> --strict
# 归档已完成的变更
openspec-chinese archive <change-name> --yes
```
### AI 工具斜杠命令
在支持的 AI 工具（Claude Code, Cursor 等）中：
```bash
/openspec-proposal # 创建新提案
/openspec-validate # 校验当前变更
/openspec-archive # 归档变更
```
## 自定义模板
### 创建模板
在 `openspec/templates/` 目录下创建自定义模板：
```bash
# 创建功能规格模板
openspec/templates/feature-spec.md
# 创建 API 规格模板
openspec/templates/api-spec.md
# 创建数据库变更模板
openspec/templates/db-migration-spec.md
```
### 模板示例
```markdown
<!-- openspec/templates/feature-spec.md -->
## ADDED Requirements
### Requirement: [功能名称]
系统 MUST [功能描述]。
#### Scenario: [主要场景]
- **WHEN** [前置条件]
- **THEN** [预期结果]
- **AND** [额外条件]
#### Scenario: [错误场景]
- **WHEN** [异常情况]
- **THEN** [错误处理]
- **AND** [用户提示]
## MODIFIED Requirements
（如有修改现有功能，在此说明）
## REMOVED Requirements
（如有废弃功能，在此说明原因和迁移路径）
```
### 使用模板
```bash
# 创建新变更时，从模板复制
cp openspec/templates/feature-spec.md openspec/changes/new-feature/specs/feature.md
# 然后填充具体内容
```
## 最佳实践
### 1. 提案阶段多花时间
- ✅ 与 AI 充分沟通，澄清所有疑问
- ✅ 详细拆解任务到可执行的粒度
- ✅ 确保 proposal.md 中的 Why/What/Impact 清晰
- ❌ 不要急于开始编码，需求不明会导致大量返工
### 2. 规格要具体可验证
- ✅ 每个需求至少有 1-2 个 Scenario
- ✅ Scenario 要具体，可直接转化为测试用例
- ✅ 包含正常流程和异常流程
- ❌ 避免模糊描述，如"系统应该快速响应"
### 3. 利用 validate 命令
```bash
# 每次编辑规格后立即校验
openspec-chinese validate <change> --strict
# 配置 Git pre-commit hook
npm run validate:chinese
```
### 4. 保持规范与代码同步
- ✅ 代码实现后，确保规范准确反映最终结果
- ✅ 如有偏差，更新规范或代码使其一致
- ✅ 归档前再次审查规范的准确性
### 5. 利用 project.md
```markdown
<!-- openspec/project.md -->
# 项目上下文
## 技术栈
- 前端: React 18 + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL 14
## 架构约定
- RESTful API 设计
- JWT 认证
- 统一错误处理中间件
## 编码规范
- ESLint + Prettier
- 函数式组件优先
- 使用 React Query 管理服务端状态
```
完善的 `project.md` 能让 AI 生成更符合项目规范的代码。
### 6. 版本兼容
OpenSpec 中文版与英文版**完全兼容**：
```bash
# 切换到中文版
openspec-chinese update
# 切换回英文版
openspec update
```
两个版本可以在团队中并存，规范文件格式完全一致。
## 常见问题排查
### 命令不可用
**症状**：`openspec-chinese: command not found`
**解决方案**：
```bash
# 检查是否在 PATH 中
which openspec-chinese # Mac/Linux
where openspec-chinese # Windows
# 检查 npm 全局 bin 路径
npm config get prefix
# 重新安装
npm uninstall -g @org-hex/openspec-chinese
npm install -g @org-hex/openspec-chinese@latest
```
### 斜杠命令未出现
**症状**：AI 工具中看不到 `/openspec-*` 命令
**解决方案**：
```bash
# 执行更新命令
openspec-chinese update
# 重启 IDE/AI 工具
# 检查是否生成了 AGENTS.md
ls openspec/AGENTS.md
```
### 校验报错
**常见错误**：
1. **缺少 Delta 分区**
```plain
Error: Missing required Delta sections (ADDED/MODIFIED/REMOVED)
```
解决：确保至少有一个 Delta 分区
2. **缺少 MUST/SHALL 关键词**
```plain
Error: Requirement missing mandatory keywords
```
解决：在需求描述中添加 MUST/SHALL/SHOULD
3. **Scenario 层级错误**
```plain
Error: Scenario must be under a Requirement
```
解决：确保 `#### Scenario:` 在 `### Requirement:` 之下
4. **Gherkin 关键字使用中文**
```plain
Error: Gherkin keywords must be in English
```
解决：使用 WHEN/THEN/AND 而非"当/那么/并且"
### 归档失败
**症状**：`openspec-chinese archive` 报错
**可能原因**：
- 变更未通过校验
- specs/ 目录为空
- Git 冲突
**解决方案**：
```bash
# 先校验格式
openspec-chinese validate <change> --strict
# 检查 specs/ 目录
ls openspec/changes/<change>/specs/
# 解决 Git 冲突后重试
git status
```
## 触发场景
本技能应在以下场景**主动调用**：
### 明确触发
1. 用户提及 "openspec"
2. 用户提及 "规范文档"、"需求文档"
3. 用户提及 "spec-driven development"
4. 用户询问如何管理需求
### 上下文触发
6. 用户开始新功能开发前（建议使用 OpenSpec）
7. 用户抱怨 AI 理解偏差或频繁返工
8. 用户询问如何让 AI 更准确理解需求
9. 用户需要生成技术文档
### 项目阶段触发
10. 项目初始化阶段（建议配置 OpenSpec）
11. 准备重大重构时（建议先写规范）
12. 团队协作场景（提供统一的需求描述）
## 执行长任务时的注意事项
1. **及时更新任务文件**：
> **必须要**及时更新对应任务的 `tasks.md` 任务进度文件。避免出现大批量完成任务后，没有更新进度文件的情况，带来严重的误解。
2. 启动**多个子代理**分模块并行完成任务：
> 务必要启动多个在后台运行的子代理，同时完成 openspec 设定的一系列繁杂的任务。以便加快速度。你应该至少同时启用至少 4 个子代理。并根据情况，主动增加足够数量的子代理完成任务。
3. 回复文本语言：
> 务必用**中文**回复用户。
4. 上下文合并后重新阅读一次任务要求：
> 为了避免你在自动合并上下文的时候，给后续的任务带来明显的幻觉，你应该及时的重新阅读 openspec 的任务规范要求。
5. 连续的，持续的执行长任务：
- 你应该一次性完成 `tasks.md` 所记录的全部任务。你应该同时新建多个子代理，做出合理的任务划分，一次性完成任务。
- 不要在完成一个任务的时候就停下来询问用户。这种停顿方式很低效率，你要避免这种执行方式。
6. **禁止**编写脚本完成批处理任务：
- **不允许**你编写任何 Python、typescript、javascript，或 bash 脚本，完成大批量代码删改之类的任务。
- 你应该阅读文件来完成更改，而不是使用不稳定的，容易带来语法错误的，删改不干净不合理的批处理脚本，来完成任务。
- 你应该新建多个子代理，用具体的子代理来完成大规模的修改任务。
7. 主从代理的调度设计：
- `主代理的职责`： 主代理应该负责全面的，完整的阅读来自 openspec 目录下全部的 markdown 文档任务要求。并按照模块和错误类型，新建足够数量的子代理。并持续监听，定期收集来自子代理的处理反馈。
- `子代理的职责`： 子代理应该严格按照主代理给定的要求来完成任务。
8. 什么情况下应该新建子代理？在以下的几种情况下，主代理应该及时新建子代理来完成任务：
- 大规模的代码探索与信息收集任务。
- 访问 url 获取文档信息的任务。
- 指定严格顺序的代码修改任务。
- 报告编写任务。
- 进度文件更新与编写任务。
## 注意事项
### 格式要求（严格遵守）
1. ✅ Delta 分区标题必须使用**英文**（ADDED/MODIFIED/REMOVED）
2. ✅ Gherkin 关键字必须使用**英文**（WHEN/THEN/AND/GIVEN）
3. ✅ 需求描述中必须包含 MUST/SHALL/SHOULD 等**强制关键词**
4. ✅ 删除需求时必须提供 **Reason** 和 **Migration**
5. ✅ 每个 Requirement 至少有**一个 Scenario**
### 工作流建议
1. ⏰ 提案阶段多花时间，实施阶段会快很多
2. 📝 规格要具体可验证，能直接转化为测试用例
3. ✅ 每次编辑后立即运行 `validate --strict`
4. 🔄 保持规范与代码同步，归档前再次审查
5. 📚 善用 `project.md` 提供项目上下文
### 团队协作
1. 👥 规范文件适合 Code Review
2. 📖 `changes/` 目录中的提案可作为 PR 描述
3. 🔍 归档后的 `specs/` 成为团队共识
4. 🌍 中英文版本可并存，格式完全兼容
### 工具集成
1. 🤖 支持 20+ AI 编程工具，无缝集成
2. 🔒 完全本地执行，无需 API 密钥
3. 📂 AGENTS.md 提供通用兼容性
4. ⚡ 斜杠命令提供快捷操作
---
## 参考资源
- **OpenSpec 中文版仓库**: https://github.com/hex-novaflow-ai/OpenSpec-Chinese
- **OpenSpec 原版仓库**: https://github.com/Fission-AI/OpenSpec
- **介绍教程**: https://www.aivi.fyi/llms/introduce-OpenSpec
- **官方文档**: 项目 README 和 docs 目录
全局agents.md推荐：
AGENTS.md.txt (18.9 KB)
config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
【31】 # 指令覆盖
【32】
config是与服务器"打交道"的配置，Agents.是操作指南,告诉Ai在操作Project如何去做。
比如是一辆车，如果Agents是大脑是车机控制系统，来操作车的自动驾驶。那么config就是底盘。通过config切换不同底盘。
“道路"就是我们的项目,Agents.md写的太好，底盘不好，驾驶起来照样别扭.想象一下你是全国第一赛车手，但是你驾驶的是一辆老头乐，那么必然发挥不出来。
这就是木桶效应！！！所以我们一定要对齐短板。
【33】 [shell_environment_policy] # inherit：all（默认） | core | none # 控制子进程继承哪些环境变量 inherit = "all" # 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true # 设置为 false 会更严格地清理敏感环境变量 ignore_default_excludes = true # 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[] # 可添加自定义的敏感变量模式 exclude = [] # 显式 key/value 覆盖（始终优先）。默认：{} # 强制设置特定的环境变量 set = {} # 白名单；若非空，则只保留匹配的变量。默认：[] # 只保留匹配这些模式的变量 include_only = [] # 实验性：通过用户 shell profile 运行。默认：false # 是否加载用户的 shell 配置文件（如 .bashrc, .zshrc） experimental_use_profile = false
【34】 # 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。 [sandbox_workspace_write] # 除工作区（cwd）外额外允许写入的根目录。默认：[] # 可添加多个受信任的写入目录 writable_roots = [] # 允许在沙箱内进行出站网络访问。默认：false # 启用后，工具可以访问网络资源，有安全风险 network_access = false # 将 $TMPDIR 从可写根目录中排除。默认：false # 防止临时目录被意外写入 exclude_tmpdir_env_var = false # 将 /tmp 从可写根目录中排除。默认：false exclude_slash_tmp = false
【35】 # 认证与登录
【36】 # 推理与详细度（支持 Responses API 的模型）
【37】 # 内置包括： # - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY） # - oss（Chat Completions API；默认指向 http://localhost:11434/v1） [model_providers] # --- 示例：用显式 base URL 或 headers 覆盖 OpenAI --- # [model_providers.openai] # name = "OpenAI" # base_url = "https://api.openai.com/v1 " # 未设置时的默认值 # wire_api = "responses" # "responses" | "chat"（默认因情况而异） # # requires_openai_auth = true # 内置 OpenAI 默认 true # # request_max_retries = 4 # 默认 4；最大 100 # # stream_max_retries = 5 # 默认 5；最大 100 # # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟） # # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token # # http_headers = { "X-Example" = "value" } # # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" } # --- 示例：Azure（根据端点选择 Chat/Responses）--- # [model_providers.azure] # name = "Azure" # base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai " # wire_api = "responses" # 或按端点使用 "chat" # query_params = { api-version = "2025-04-01-preview" } # env_key = "AZURE_OPENAI_API_KEY" # # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY" # --- 示例：本地 OSS（例如 Ollama 兼容）--- # [model_providers.ollama] # name = "Ollama" # base_url = "http://localhost:11434/v1" # wire_api = "chat"
【38】
感谢分享
【39】
有的佬，但是MCP windows\MacOS 配置路径不同我发出发不一定能使用成功，我等下出一版两个系统的 MCP 配置项。这样应该好一点
【40】 # 项目文档控制
【41】 # 将特定 worktree 标记为可信或不可信。 # 为不同项目设置不同的信任级别 [projects] # 项目路径设置示例 # [projects."/absolute/path/to/project"] # trust_level = "trusted" # 或 "untrusted"
【42】 # 集中式功能开关（推荐）
【43】 # 核心模型选择
【44】 # UI、通知与杂项
【45】 # UI、通知与杂项（表）
【46】
这配置好全，感谢佬友
【47】
原来如此
【48】 [mcp_servers] # --- 示例：STDIO 传输 --- # [mcp_servers.docs] # enabled = true # 可选；默认 true # command = "docs-server" # 必填：启动服务器的命令 # args = ["--port", "4000"] # 可选：命令行参数 # env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value # env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量 # cwd = "/path/to/server" # 可选：工作目录覆盖 # startup_timeout_sec = 10.0 # 可选；默认 10.0 秒，启动超时 # # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名 # tool_timeout_sec = 60.0 # 可选；默认 60.0 秒，工具调用超时 # enabled_tools = ["search", "summarize"] # 可选：允许列表，只启用指定工具 # disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效） # --- 示例：可流式 HTTP 传输 --- # [mcp_servers.github] # enabled = true # 可选；默认 true # url = "https://github-mcp.example.com/mcp " # 必填：MCP 服务器 URL # bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token> # http_headers = { "X-Example" = "value" } # 可选：静态请求头 # env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头 # startup_timeout_sec = 10.0 # 可选 # tool_timeout_sec = 60.0 # 可选 # enabled_tools = ["list_issues"] # 可选：允许列表
【49】
不错 不过没有mcp相关工具的提示词
【50】
wok，太牛了
【51】 # 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。 # 用于添加全局自定义指令，优先级高于 AGENTS.md # developer_instructions = "" #（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。 # 此选项已弃用，建议使用 AGENTS.md 文件 # instructions = "" # 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。 # 自定义历史压缩的提示词，影响会话历史如何被压缩 # compact_prompt = "" # 用文件路径覆盖内置的基础指令。默认：未设置。 # 从外部文件加载自定义指令 # experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt" # 从文件加载历史压缩提示词覆盖。默认：未设置。 # 从外部文件加载自定义压缩提示词 # experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
【52】 # OpenTelemetry（OTEL）- 默认禁用
【53】 # 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none # 控制 Codex 生成的文件链接如何在编辑器中打开 file_opener = "vscode"
【54】
review的模型是消耗周限吗还是额外那个review额度
【55】 # 使用统一执行工具代替单独的命令工具（实验性） experimental_use_unified_exec_tool = false # 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false # 允许更灵活的补丁应用方式 experimental_use_freeform_apply_patch = false
【56】 # Projects（信任级别）
【57】 [history] # save-all（默认） | none # 控制是否保存命令历史 persistence = "save-all" # 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880 (5MB) # 限制历史文件大小，防止无限增长 # max_bytes = 0
【58】 # Skills（按技能覆盖）
【59】
agents.md不用改吗
【60】
还能配置这么多，学习了
【61】 [profiles] # 定义配置文件预设，可快速切换不同配置组合 # [profiles.default] # model = "gpt-5.2-codex" # model_provider = "openai" # approval_policy = "on-request" # sandbox_mode = "read-only" # oss_provider = "ollama" # model_reasoning_effort = "medium" # model_reasoning_summary = "auto" # model_verbosity = "medium" # chatgpt_base_url = "https://chatgpt.com/backend-api/ " # experimental_compact_prompt_file = "./compact_prompt.txt" # include_apply_patch_tool = false # experimental_use_unified_exec_tool = false # experimental_use_freeform_apply_patch = false # tools_web_search = false # features = { unified_exec = false }
【62】 # CLI 登录凭据的持久化方式：file（默认） | keyring | auto # file：保存在文件中；keyring：使用系统密钥环；auto：自动选择 cli_auth_credentials_store = "file" # ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认： # 用于 ChatGPT 网页登录的端点 chatgpt_base_url = "https://chatgpt.com/backend-api/ " # 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。 # 用于企业/团队账号的 workspace 隔离 # forced_chatgpt_workspace_id = "" # 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。 # 可选值：chatgpt | api # forced_login_method = "chatgpt" # MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring # 控制 MCP 服务器的 OAuth 令牌存储位置 mcp_oauth_credentials_store = "auto"
【63】 [tui] # 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true # 可设置为 false 禁用通知，或指定特定事件类型 # 示例：false | ["agent-turn-complete", "approval-requested"] notifications = false # 启用欢迎/状态/加载动画。默认：true # 控制是否显示 TUI 动画效果 animations = true # 在欢迎界面显示入门提示。默认：true # 新用户引导提示 show_tooltips = true # 可选的 TUI2 滚动调优（未设置则使用默认值）。 # 滚动灵敏度设置（高级用户） # scroll_events_per_tick = 0 # scroll_wheel_lines = 0 # scroll_trackpad_lines = 0 # scroll_trackpad_accel_events = 0 # scroll_trackpad_accel_max = 0 # scroll_mode = "auto" # auto | wheel | trackpad # scroll_wheel_tick_detect_max_ms = 0 # scroll_wheel_like_max_duration_ms = 0 # scroll_invert = false # 控制用户是否可以通过 `/feedback` 提交反馈。默认：true [feedback] enabled = true # 产品内提示（多由 Codex 自动设置）。 [notice] # 隐藏完整访问权限警告 # hide_full_access_warning = true # 隐藏全局可写警告 # hide_world_writable_warning = true # 隐藏速率限制模型提示 # hide_rate_limit_model_nudge = true # 隐藏 GPT 5.1 迁移提示 # hide_gpt5_1_migration_prompt = true # 隐藏 GPT-5.1-codex-max 迁移提示 # "hide_gpt-5.1-codex-max_migration_prompt" = true # 模型迁移映射，旧模型 -> 新模型 # model_migrations = { "gpt-4.1" = "gpt-5.1" }