CX-04 项目指令、配置、权限与沙盒：让 App 知道怎么安全工作

项目说明层：AGENTS.md
  -> 告诉 Codex 项目事实、命令、规范和安全边界
 
用户偏好层：App Settings / config.toml
  -> 设置模型、终端、审批、沙盒、MCP、插件等
 
命令策略层：Rules / permission profiles
  -> 对命令、目录、网络和危险动作建立可执行边界
 
事件脚本层：Hooks
  -> 在特定时机运行真实脚本，做审计、检查或自动化

Read this project. Report:
1. what this project does
2. the install command
3. the test command
4. the main source and docs directories
5. files or directories that should not be changed casually
 
Do not modify files.

# AGENTS.md
 
这份文件约束 Codex 在本项目里的工作方式，用来减少常见的 AI 编程失误。你可以在此基础上继续补充项目专属规则。
 
参考来源：https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md
 
取舍说明：这些规则更偏向谨慎和可验证，而不是最快完成。遇到很小的简单任务时，可以按实际情况简化流程。
 
## 项目背景
 
开始修改前，先阅读 README、配置文件和目录结构，确认项目目标、技术栈和关键目录；不要凭经验猜。
 
## 常用命令
 
在 Codex App 终端里只运行项目已经证明存在的命令。优先从 README、脚本清单、构建配置、CI workflow 和上一轮 Review 记录里确认；找不到就先只读检查，不要让 Codex 现场编一个。
 
不要把示例命令写成项目事实；没有确认过的命令不要写进本文件，也不要留下占位文本。
 
## 1. 写代码前先想清楚
 
不要假装已经理解，也不要把不确定性藏起来。该说清楚的地方先说清楚。
 
开始实现前：
 
- 先在当前 thread 里写出任务边界、将要读取的文件和不会碰的目录。
- 需求可能有多种解释时，先用 `/plan` 或自然语言列出分支，再让用户选。
- 发现更小的 App 工作流能解决问题时，优先提出，例如只读 Review、只改文档、只跑测试。
- 当请求会扩大权限、绕过 Review 或触碰敏感文件时，先停下来说明风险。
 
## 2. 简单优先
 
只写解决当前问题所需的最少代码，不做猜测式扩展。
 
- 不把一次 App thread 做成“顺手重构全项目”。
- 不因为 Codex 能开 worktree，就把小修拆成复杂分支流程。
- 不新增 Settings、Rules、Hooks 或 profile 字段，除非本任务确实需要。
- 不替未来想象场景写大段配置；先让当前 diff 可读、可审、可回滚。
- 如果 Review 面板里出现无关文件，先收窄而不是继续解释。
 
自检问题：资深工程师看到这段实现，会不会觉得过度设计？如果会，就删减。
 
## 3. 外科手术式修改
 
只碰必须修改的地方。只清理自己造成的问题。
 
编辑已有代码时：
 
- Codex 每次改动都要能在 Review 面板里解释给人看。
- 不把格式化、重命名、目录移动混进业务修复。
- 沿用项目已有风格、脚本和测试入口；不要把别的仓库习惯搬进来。
- 看到无关问题，放到后续任务建议里，不在当前 thread 直接处理。
 
如果你的改动制造了无用内容：
 
- 删除由本次改动造成的无用 import、变量、函数。
- 不删除本来就存在的死代码，除非任务明确要求。
 
检查标准：每一行改动都应该能追溯到用户这次请求。
 
## 4. 目标驱动执行
 
把任务转成可验证的目标，然后循环到验证完成。
 
示例：
 
- “加校验” -> “先在 App 里确认输入路径和失败用例，再改最小文件”
- “修 bug” -> “先复现或写出复现条件，再让 Review 只显示相关 diff”
- “重构 X” -> “先说明为什么必须重构，再用测试和 Review 证明行为没变”
 
多步骤任务先写简短计划：
 
```text
1. [步骤] -> 验证：[检查方式]
2. [步骤] -> 验证：[检查方式]
3. [步骤] -> 验证：[检查方式]
```

# Project Instructions
 
## Overview
 
这是一个 Next.js 应用，主代码在 `src/`，测试在 `tests/`。
 
## Commands
 
- 安装依赖：`npm install`
- 开发服务：`npm run dev`
- 类型检查：`npm run typecheck`
- 单元测试：`npm test`
- 格式检查：`npm run lint`
 
## Code Style
 
- 使用 TypeScript strict mode。
- 不新增 `any`。
- 复用现有组件和工具函数。
 
## Testing
 
- 修改业务逻辑时补充或更新测试。
- 提交前至少运行相关测试。
 
## Safety
 
- 不读取或修改 `.env*`。
- 不提交真实密钥。
- 不直接改数据库迁移，除非任务明确要求。

repo/
  AGENTS.md
  apps/web/AGENTS.md
  packages/api/AGENTS.md

根 AGENTS.md：所有包都用 npm test
apps/mobile/AGENTS.md：移动端包使用 pnpm test

# apps/mobile/AGENTS.md
 
本文件只适用于 apps/mobile 下的 React Native 包。
在本目录内，测试命令使用 pnpm test；不要套用根目录 npm test 示例。

# 只作为结构提示，实际字段以官方 Config Reference 和当前 App 为准。
# 不要把模型名、实验开关或公司密钥硬写进教程示例。

# ~/.codex/rules/default.rules 或受信任项目里的 .codex/rules/default.rules
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "查看 PR 可以，但需要确认目标仓库和输出字段。",
    match = [
        "gh pr view 123",
        "gh pr view --repo owner/repo 123",
    ],
    not_match = [
        "gh pr checkout 123",
    ],
)

某个事件发生
  -> Codex 找到匹配的 hook 配置
  -> 需要信任的 hook 先走 trust review
  -> hook 命令在当前 session cwd 里运行
  -> 输出、失败、超时都会影响体验

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/pre_tool_use_policy.py",
            "timeout": 30,
            "statusMessage": "Checking command policy"
          }
        ]
      }
    ]
  }
}

AGENTS.md
  写清项目命令、测试、禁止事项
 
App Settings
  使用默认或保守审批
 
Review
  每次改动都看 diff
 
Git
  小步提交，不混 unrelated changes

.codex/config.toml
.codex/rules/default.rules
.codex/hooks.json 或 .codex/config.toml 中的 [hooks]
CI 中的 codex review 或测试任务

# Project Instructions
 
## Overview
 
这是一个 Web 项目，主要代码在 src/，测试在 tests/。
 
## Commands
 
- Install: npm ci
- Test: npm test
- Lint: npm run lint
 
## Safety
 
- 不读取或修改 .env\*。
- 不自动提交、推送或创建 PR。
- 大范围改动前先给计划。

阅读 AGENTS.md，复述本项目的命令和安全边界。不要修改文件。

# .codex/rules/default.rules
prefix_rule(
    pattern = ["gh", "pr", "merge"],
    decision = "prompt",
    justification = "合并 PR 前需要人工确认目标仓库、分支和 CI 状态。",
    match = [
        "gh pr merge 123",
        "gh pr merge 123 --squash",
    ],
)

codex execpolicy check --pretty --rules .codex/rules/default.rules -- gh pr merge 123

AGENTS.md
tests/AGENTS.md

AGENTS.md
  - 项目是什么
  - 常用命令
  - 不读取 .env*
  - 改完展示 diff，不自动提交
 
App Settings
  - 默认或保守权限
  - 陌生项目先只读
 
Review
  - 每次改完看文件列表和 diff

AGENTS.md
  - 项目结构
  - package manager
  - test / lint / build 命令
  - 代码风格
  - 安全边界
 
.codex/rules/default.rules
  - prompt: gh pr merge
  - forbidden: 递归删除高风险目录
  - prompt: 部署命令
 
团队文档
  - App Settings 推荐 profile
  - MCP / Connector / Plugin 登记表

repo/AGENTS.md
  - 仓库总体结构
  - 全局安全规则
  - 不要跨包乱改
 
apps/web/AGENTS.md
  - Web 应用命令
  - 前端测试和构建
 
packages/api/AGENTS.md
  - API 包命令
  - 数据库和迁移边界

目标：修复 apps/web 登录页样式。
范围：只改 apps/web 下文件。
请先总结当前目录适用哪些 AGENTS.md 规则，再给计划。
不要修改 packages/api。

managed requirements
  - allowed sandbox modes
  - allowed approval policies
  - managed hooks
  - restrictive rules
  - MCP server allowlist
 
项目 AGENTS.md
  - 项目事实和验证命令
 
团队 profiles
  - read-only
  - daily-dev
  - ci
  - emergency

## Summary
 
- 改了哪一类 Codex 配置
- 目的是什么
 
## Scope
 
- 涉及 AGENTS.md / Rules / Hooks / config / MCP 中哪一层
- 不涉及哪些层
 
## Verification
 
- 新线程是否读到 AGENTS.md
- Rules 是否用 execpolicy check 验证
- Hooks 是否在测试仓库触发
- MCP 是否只读试跑
 
## Risk
 
- 可能阻塞哪些命令
- Windows / macOS 是否有差异
- 如何回滚

请写高质量代码，像世界顶级工程师一样认真。

Run `pnpm test -- --runInBand` for targeted Jest checks.
Generated API clients live under `src/generated/`; do not edit them manually.
Use `src/lib/errors.ts` helpers instead of throwing plain strings.

# Project Instructions
 
## Overview
 
This is a TypeScript web app with a Next.js frontend and API routes.
 
## Common Commands
 
- Install: `pnpm install`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Typecheck: `pnpm typecheck`
 
## Code Style
 
- Prefer small functions near their call sites.
- Use existing error helpers from `src/lib/errors.ts`.
- Do not introduce new state libraries without discussion.
 
## Editing Boundaries
 
- Do not edit generated files under `src/generated/`.
- Do not change database migrations unless the task explicitly asks.
- Keep unrelated formatting changes out of functional patches.
 
## Security
 
- Never commit secrets.
- Treat `.env*` files as sensitive.
- Do not call production services from local tests.

# Repository Instructions
 
## Workspace
 
This repository contains multiple packages:
 
- `apps/web`: customer-facing web app
- `apps/admin`: internal admin app
- `packages/ui`: shared UI components
- `packages/api`: shared API clients
 
## Commands
 
- Root install: `pnpm install`
- Web test: `pnpm --filter web test`
- Admin test: `pnpm --filter admin test`
- UI lint: `pnpm --filter ui lint`
 
## Boundaries
 
- When working in one package, avoid changing sibling packages unless needed.
- Shared package changes require checking at least one downstream app.
- Do not update lockfiles unless dependency changes are part of the task.

# apps/admin Instructions
 
This app is internal-only.
 
Use existing table components from `packages/ui`.
Do not add new chart libraries.
When changing permissions UI, read `docs/admin-permissions.md` first.

1. 当前 App 线程的权限和 sandbox。
2. 当前项目里的 AGENTS.md。
3. 当前项目的 .codex/config.toml。
4. 用户级 ~/.codex/config.toml。
5. 管理员或企业受管要求。
6. CLI 启动参数或 profile override。

当前 Codex 行为和我预期不一致。
请先不要修改文件。
请帮我按层排查：
1. App 当前权限和 sandbox
2. AGENTS.md 指令
3. 项目级 config
4. 用户级 config
5. MCP / Skills / Plugins 是否可见
6. 是否有企业受管策略影响

default_permissions = "project-edit"
 
[permissions.project-edit]
description = "Project editing with narrow network access."
extends = ":workspace"
 
[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"
"src/generated/**" = "read"
 
[permissions.project-edit.network]
enabled = true
 
[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

- 不知道任务会运行什么命令。
- 项目里有生产密钥或客户数据。
- 自动化后台运行。
- 子代理会并行执行。
- 外部插件或 MCP 会参与。

- 写复杂业务流程。
- 替代测试。
- 替代 Review。
- 判断产品取舍。
- 管理外部账号授权。

# .codex/rules/default.rules
 
def prefix_rule(argv):
    if len(argv) >= 2 and argv[0] == "git" and argv[1] == "push":
        return "prompt"
    if len(argv) >= 3 and argv[0] == "git" and argv[1] == "push" and "--force" in argv:
        return "deny"
    return None

def prefix_rule(argv):
    readonly = [
        ["git", "status"],
        ["git", "diff"],
        ["git", "log"],
        ["rg"],
        ["ls"],
    ]
    for prefix in readonly:
        if argv[:len(prefix)] == prefix:
            return "allow"
    return None

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/check_prompt_for_secrets.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/log_bash_use.py",
            "statusMessage": "Recording command use"
          }
        ]
      }
    ]
  }
}

1. 这个 hook 在什么事件触发？
2. 它会运行什么命令？
3. 它能读取或写入哪些数据？

1. 先描述配置目标。
2. 只读当前配置和 AGENTS.md。
3. 生成最小变更计划。
4. 修改配置。
5. 新开线程或重启 Codex 验证是否生效。
6. 记录给团队看的变更说明。

我想收窄 Codex 在这个项目里的权限。
请先只读查看 AGENTS.md、.codex/config.toml 和相关 rules 文件。
给我一个最小变更方案。
不要直接修改，直到我确认。

## Summary
 
- Add a project-level Codex permission profile.
- Deny `.env*` files.
- Keep generated files read-only.
 
## Why
 
- Reduce accidental edits to sensitive and generated files.
 
## How To Use
 
- Restart Codex after pulling this change.
- Open a new thread in the project.

1. 默认 sandbox 模式。
2. 是否允许 approval_policy = "never"。
3. 哪些 MCP server 可以启用。
4. 插件共享是否允许。
5. Hooks 是否启用或受管。
6. 是否限制 full access。

# Codex Managed Config Notice
 
## What changed
 
The workspace now uses a managed Codex baseline for permissions and external tools.
 
## What developers will notice
 
- Some commands may ask for approval more often.
- Unapproved MCP servers may be disabled.
- Project hooks may need review before running.
 
## What to do
 
- Keep project commands in AGENTS.md.
- Request new MCP or plugin access through the team process.
- Do not bypass sandbox settings for convenience.

目标：降低风险，先学会 App。
做法：
- `AGENTS.md` 写项目命令。
- 默认 workspace 权限。
- 不配置复杂 hooks。
- 不接生产 MCP。

目标：让每个人用同一套边界。
做法：
- 根目录 `AGENTS.md`。
- 关键子目录补局部 `AGENTS.md`。
- Rules 拦 git push、publish、危险删除。
- MCP 只接只读文档和 PR 上下文。

目标：可审计、可回滚、可解释。
做法：
- 受管配置约束 sandbox 和审批。
- MCP allowlist。
- Hook trust 流程。
- 插件登记和共享策略。
- 自动化默认只读或 worktree。

请只读盘点当前项目，为建立 Codex 项目基线做准备。
读取：
- README
- package.json 或项目构建配置
- docs/ 中的开发说明
- 现有 AGENTS.md 或 CLAUDE.md
- .codex/ 目录如果存在
 
输出：
1. 项目事实
2. 常用命令候选
3. 敏感目录或文件
4. 适合写进 AGENTS.md 的规则
5. 适合用 Rules 管的命令风险
不要修改文件。

请根据刚才的盘点生成 AGENTS.md 草稿。
要求：
- 只写当前项目能支持的事实
- 不确定的命令标注为候选
- 不写空泛口号
- 不覆盖现有文件，先输出草稿

请把确认后的 AGENTS.md 写入项目根目录。
只创建或修改 AGENTS.md。
完成后说明：
- 哪些内容来自 README
- 哪些内容来自 package.json
- 哪些内容是安全边界

/review
请审查 AGENTS.md 是否有过度承诺、过期命令或不清楚的安全边界。

请为这个项目设计最小 rules 策略。
目标：
- git push 需要确认
- force push 拒绝
- publish 需要确认
- 只读 Git 命令允许
 
先给规则草稿和解释，不要写文件。

请总结这个项目的 Codex 基线：
1. AGENTS.md 解决了什么
2. Rules 解决了什么
3. 哪些风险还需要权限 profile 或企业配置
4. 新人使用这个项目时第一条 prompt 应该怎么写

AGENTS.md 写 `npm test`，但项目实际使用 `pnpm test`。

请核对 AGENTS.md 中的命令是否和 package.json、lockfile、README 一致。
只修改 AGENTS.md 中明显过期的命令。
不改 package.json。

所有 git 命令都被 prompt，连 git status 都很烦。

def prefix_rule(argv):
    if argv[:2] in [["git", "status"], ["git", "diff"], ["git", "log"]]:
        return "allow"
    if len(argv) >= 2 and argv[0] == "git" and argv[1] == "push":
        return "prompt"
    return None

每次工具调用后都要等很久。

请只读检查 Codex hooks 配置。
帮我找出：
1. 哪些 hooks 触发太频繁
2. 哪些脚本可能耗时过长
3. 哪些检查应该改到 Stop 或人工命令里
4. 哪些 hook 可以先禁用

同事能用 MCP，我这里看不到。

请帮我比较项目级和用户级 Codex 配置可能的差异。
重点看：
- MCP server 是否配置在不同层
- 当前项目是否 trusted
- CODEX_HOME 是否不同
- App 和 WSL CLI 是否使用不同 home

[permissions.docs-edit]
extends = ":workspace"
 
[permissions.docs-edit.filesystem.":workspace_roots"]
"docs/**" = "write"
"README.md" = "write"
"src/**" = "read"
"**/.env*" = "deny"

[permissions.app-edit]
extends = ":workspace"
 
[permissions.app-edit.filesystem.":workspace_roots"]
"src/**" = "write"
"tests/**" = "write"
"docs/**" = "write"
"migrations/**" = "read"
"**/.env*" = "deny"

default_permissions = ":read-only"

- Codex 必须知道哪些命令？
- 哪些目录可以默认修改？
- 哪些目录只能读？
- 哪些操作必须先问人？
- 哪些外部能力需要登记？
- 哪些文档或课程内容需要核对事实？

# Project Instructions
 
## Commands
 
- Test:
- Lint:
- Build:
 
## Scope
 
- Codex may edit `src/`, `tests/`, and `docs/` when the task asks.
- Do not edit generated files.
- Ask before changing migrations.
 
## Safety
 
- Do not read or modify `.env*`.
- Ask before running publish, deploy, or push commands.
- Keep bug fixes small unless the user asks for refactoring.

- 根目录 AGENTS.md。
- 写项目命令。
- 写敏感文件提醒。
- 不上复杂 Hooks。

- 根据真实任务补充 AGENTS.md。
- 加 Rules 拦 push、publish、危险删除。
- 记录常见 prompt。
- 修正过期命令。

- 拆子目录 AGENTS.md。
- 设计权限 profile。
- 引入只读 MCP。
- 建立 Plugin 和 Automation 登记。

- 受管配置。
- MCP allowlist。
- Hook trust 流程。
- 月度配置复盘。

请审查 AGENTS.md。
重点看：
1. 命令是否能从项目文件找到依据
2. 是否有空泛口号
3. 安全边界是否清楚
4. 是否把一次性任务写成长期规则
5. 是否遗漏 generated、migrations、env 文件说明

请审查 rules 文件。
重点看：
1. 是否误拦只读命令
2. 是否漏掉 push、publish、force push
3. 是否有过宽 allow
4. 是否容易让正常开发频繁 prompt

请审查 hooks 配置。
重点看：
1. 触发事件是否合理
2. 命令是否可信
3. 是否会读取敏感文件
4. 是否会拖慢每次工具调用
5. 是否需要 trust review

请审查权限 profile。
重点看：
1. workspace roots 是否正确
2. deny 规则是否覆盖敏感文件
3. generated 是否只读
4. network domains 是否过宽
5. 是否使用了不适合默认的 full access

别乱改支付相关代码。

## Payment Area
 
Payment code is high risk.
 
Before editing files under `src/payment/`, Codex should:
 
- Explain why the payment area is relevant to the task.
- Prefer read-only analysis first.
- Ask before changing payment flow, billing logic, or migration files.
 
Do not include payment refactors in unrelated PRs.

本次只修 auth redirect。
不要修改 `src/payment/`、billing、checkout 或 migration 文件。
如果你认为这些文件相关，请先停下来说明原因。

目标：
- 普通任务默认不碰 payment。
- 需要 payment 修改时，人要明确确认。
- 发布、迁移、push 仍由人执行。

每次都要跑测试。

## Testing
 
Use the narrowest relevant test first.
 
Common commands:
 
- `npm test -- auth`
- `npm test -- checkout`
- `npm run lint`
 
If tests are not run, explain why and what should be run manually.
Do not claim tests passed without command output.

修完后运行 auth redirect 相关测试。
如果不能运行，请说明原因和人工验证方式。
不要写“已验证”，除非你真的看到命令结果。

AGENTS.md：修改 generated 文件前必须确认。
当前 prompt：帮我更新所有生成文件。
Rules：禁止运行 broad formatter。
Codex 计划：运行 format all 并更新 generated。

请只读分析当前指令冲突。
 
已知：
1. AGENTS.md 要求修改 generated 文件前确认。
2. 当前 prompt 要更新所有生成文件。
3. Rules 限制 broad formatter。
 
请输出：
1. 哪些动作可以直接做。
2. 哪些动作需要确认。
3. 哪些动作被规则限制。
4. 推荐的安全下一步。
 
不要修改文件。

- 先只读列出 generated 文件。
- 说明为什么需要更新。
- 请求用户确认具体文件范围。
- 不运行 broad formatter，只运行 narrow command。

只更新以下 generated 文件：
- src/generated/api-types.ts
 
不要运行全项目 formatter。
不要更新其他 generated 文件。
修改后说明生成来源和验证方式。

请只读复盘这次 Codex 改动越界。
 
背景：
- 目标是更新 README 安装说明。
- 实际 diff 包含 package.json scripts 修改。
 
输出：
1. prompt 里哪里没有限制清楚。
2. AGENTS.md 是否缺少边界。
3. 是否需要 Rules 或权限限制。
4. 下次同类任务应该怎么写 prompt。
5. 不要修改文件。

## Documentation-Only Tasks
 
When the user asks for documentation-only edits:
 
- Do not modify package files.
- Do not modify source code.
- If a doc command appears wrong, report it first instead of changing scripts.

只更新 README 安装说明。
不要修改 package.json、lockfile、源码或配置。
如果发现 README 命令和 package scripts 不一致，只报告不修改。

# AGENTS.md
 
这份文件约束 Codex 在本项目里的工作方式。
 
参考来源：https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md
 
## 项目背景
 
开始修改前，先阅读 README、配置文件和目录结构，确认项目目标、技术栈和关键目录；不要凭经验猜。
 
## 常用命令
 
只写本项目已经确认过的真实命令。不要保留示例命令或占位文本。
 
## 1. 写代码前先想清楚
 
- 先确认需求、影响范围和验证方式。
- 信息不足时先问，不根据经验猜项目规则。
- 有多种方案时，先说明权衡，再选择适合当前任务的方案。
 
## 2. 简单优先
 
- 只实现当前任务需要的内容。
- 不主动新增框架、依赖、配置项或抽象层。
- 能用小改动解决，就不用大改动。
 
## 3. 外科手术式修改
 
- 保持改动集中，不顺手重构无关代码。
- 优先使用项目已有写法。
- 不统一格式化无关文件。
- 发现无关问题可以说明，不直接处理。
 
## 4. 目标驱动执行
 
- 复杂任务先拆成可检查的小步骤。
- 每一步都写清楚验证方式。
- 计划不成立时先说明原因，再调整。
 
## 安全边界
 
- 不读取 `.env*`。
- 不提交密钥、Token、证书。
- 不编辑生成文件，除非任务明确要求。
 
## 验证要求
 
- 改源码后运行相关测试；无法运行时说明原因。
- 最终回复说明改了什么、验证了什么、还剩什么风险。
 
## 这些规则生效时应该看到
 
- diff 能清楚对应本次需求。
- 无关改动少。
- 结果有测试或检查步骤支撑。