docs(repo): 统一 AGENTS 入口和开发容器命名

将目录级 README 迁移为就近 AGENTS.md，并在根 AGENTS、docs/AGENTS、crates/AGENTS 和模板中明确 AGENTS-first 的文档路由规则。

收敛 Dev Container 规则到 simplekernel-devcontainer 命名体系，补充 .devcontainer/AGENTS.md，统一本地镜像、常驻容器和 GHCR 镜像名称，并让 README、CONTRIBUTING、docs/docker 和 CI workflow 使用同一套入口。

移除 CI 中临时安装 rustup/cargo-deny 的兜底路径，要求开发镜像提供工具链，并让 dev-image workflow 覆盖整个 .devcontainer 配置面。

Verification:

- jq empty .devcontainer/devcontainer.json

- ruby YAML parse for dev-image.yml, workflow.yml, docs.yml, setup action

- git diff --cached --check

- staged sensitive-text scan

Co-authored-by: OpenAI Codex <codex@openai.com>
Signed-off-by: Niu Zhihong <zhihong@nzhnb.com>

Author: MRNIU

.devcontainer/AGENTS.md

@@ -0,0 +1,82 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
+# Dev Container
+
+本目录定义 SimpleKernel 的开发、CI 和 QEMU 系统测试容器环境。宿主机只负责 Git、Docker
+或兼容容器运行时、编辑器 / AI agent，以及 Dev Container CLI；Rust nightly、交叉编译器、
+QEMU、固件构建依赖、pre-commit、Mermaid 和 GitHub CLI 都在容器内使用。
+
+## 命名规则
+
+本仓库使用自己的容器和镜像命名，不继承其他项目名称。
+
+| 用途 | 名称 |
+|------|------|
+| Dev Container 显示名 | `simplekernel-devcontainer` |
+| 本地开发镜像 | `simplekernel-devcontainer:latest` |
+| 常驻 Dev Container 容器名 | `simplekernel-devcontainer-{username}-{branch}` |
+| CI / GHCR Dev Container 镜像 | `ghcr.io/simple-xx/simplekernel-devcontainer:{latest,sha}` |
+| 项目运行时容器 | 无；内核只在 Dev Container 内启动的 QEMU 中运行 |
+
+`username` 和 `branch` 必须归一化为 Docker 容器名允许的字符。`branch` 来自当前具名
+Git 分支；detached HEAD 状态不得启动常驻 Dev Container。不要依赖 Docker 自动生成的
+随机名称作为常规入口。
+
+## 启动入口
+
+使用编辑器 Dev Container 或 CLI 前，先在宿主机 shell 中设置本仓库命名规则要求的
+`DEVCONTAINER_NAME`：
+
+```bash
+DEVCONTAINER_USER="$(id -un | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+DEVCONTAINER_BRANCH="$(git branch --show-current | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+if [ -z "$DEVCONTAINER_BRANCH" ]; then
+  echo "detached HEAD is not allowed for the devcontainer name" >&2
+  exit 1
+fi
+export DEVCONTAINER_NAME="simplekernel-devcontainer-${DEVCONTAINER_USER}-${DEVCONTAINER_BRANCH}"
+```
+
+标准入口：
+
+```bash
+devcontainer up --workspace-folder .
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask build --arch riscv64
+```
+
+`devcontainer exec --workspace-folder . <command>` 也可用于临时交互，但文档化验证和 PR
+证据优先写成 `docker exec -w /workspace "$DEVCONTAINER_NAME" <command>`，这样容器名、
+工作目录和复用边界都明确。
+
+## 手动 Docker fallback
+
+没有 Dev Container CLI，或正在排查 Dev Container CLI 本身时，才手动创建常驻容器。
+`docker run` 只用于创建后台容器；项目命令仍通过 `docker exec` 执行。
+
+```bash
+docker build --pull=false -f .devcontainer/Dockerfile -t simplekernel-devcontainer:latest .devcontainer
+docker inspect "$DEVCONTAINER_NAME" >/dev/null 2>&1 || docker run -d \
+  --name "$DEVCONTAINER_NAME" \
+  --mount "type=bind,src=$(pwd),dst=/workspace" \
+  -w /workspace \
+  simplekernel-devcontainer:latest sleep infinity
+if [ "$(docker inspect -f '{{.State.Running}}' "$DEVCONTAINER_NAME")" != "true" ]; then
+  docker start "$DEVCONTAINER_NAME" >/dev/null
+fi
+docker exec -w /workspace "$DEVCONTAINER_NAME" git config --global --add safe.directory /workspace
+```
+
+重建同名容器前，先确认旧容器没有需要保留的状态。需要保留的内核、固件、文档或测试产物
+必须写回当前仓库的 `target/`、`docs-out/` 或文档声明的产物目录。
+
+## 产物路径
+
+| 产物 | 宿主机路径 | 容器内路径 | 说明 |
+|------|------------|------------|------|
+| Cargo 产物 | `target/` | `/workspace/target/` | 内核 ELF、调试文件、启动目录和固件 |
+| 固件产物 | `target/firmware/<arch>/` | `/workspace/target/firmware/<arch>/` | OpenSBI、U-Boot、OP-TEE、ATF 输出 |
+| 启动产物 | `target/<target-triple>/<profile>/boot/` | `/workspace/target/<target-triple>/<profile>/boot/` | `boot.fit`、`boot.scr.uimg`、`rootfs.img` |
+| 文档发布产物 | `docs-out/` | `/workspace/docs-out/` | `docs.yml` 生成并上传的 Pages artifact |
+| 临时文件 | `.tmp/` | `/workspace/.tmp/` | 可清理暂存 |
+
+不要把唯一产物留在容器临时文件系统、匿名 volume、`/tmp`、`/home/dev`、上级目录或项目外缓存目录。

.devcontainer/Dockerfile

@@ -135,5 +135,14 @@ RUN cargo install --locked cargo-deny && \
     cargo install --locked mdbook && \
     chmod -R a+w "$CARGO_HOME"
 
+# Dev Container 交互用户。构建阶段仍使用 root 安装工具，运行阶段使用 dev。
+RUN useradd -m -s /usr/bin/zsh dev && \
+    echo 'dev ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/dev && \
+    chmod 0440 /etc/sudoers.d/dev && \
+    mkdir -p /workspace && \
+    chown dev:dev /workspace
+
 # 默认 shell 设为 zsh
 ENV SHELL=/usr/bin/zsh
+
+WORKDIR /workspace

.devcontainer/devcontainer.json

@@ -1,9 +1,27 @@
 {
-	"name": "SimpleKernel",
+	"name": "simplekernel-devcontainer",
 	"build": {
-		"dockerfile": "Dockerfile"
+		"dockerfile": "Dockerfile",
+		"options": [
+			"--tag",
+			"simplekernel-devcontainer:latest"
+		]
 	},
-	"postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && git submodule update --init --recursive --depth 1 && rustup show",
+	"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached",
+	"workspaceFolder": "/workspace",
+	"runArgs": [
+		"--name",
+		"${localEnv:DEVCONTAINER_NAME}"
+	],
+	"remoteUser": "dev",
+	"updateRemoteUserUID": true,
+	"containerEnv": {
+		"CARGO_HOME": "/usr/local/cargo",
+		"RUSTUP_HOME": "/usr/local/rustup",
+		"CARGO_TARGET_DIR": "${containerWorkspaceFolder}/target",
+		"TMPDIR": "${containerWorkspaceFolder}/.tmp"
+	},
+	"postCreateCommand": "mkdir -p ${containerWorkspaceFolder}/target ${containerWorkspaceFolder}/.tmp && git config --global --add safe.directory ${containerWorkspaceFolder} && git submodule update --init --recursive --depth 1 && pre-commit install --install-hooks && rustup show && cargo fetch --locked && cargo --version && cargo clippy --version && rustfmt --version && qemu-system-riscv64 --version && qemu-system-aarch64 --version && mkimage -V && gh --version && pre-commit --version && mmdc --version",
 	"customizations": {
 		"vscode": {
 			"settings": {

.github/actions/setup/action.yml

@@ -25,7 +25,6 @@ runs:
         git config --global --add safe.directory '*'
         git submodule update --init --recursive --depth 1
 
-    # TODO: 合回 main 后触发 dev-image 重建，届时删除 rustup fallback 安装逻辑
     - name: Setup Rust toolchain
       shell: bash
       run: |
@@ -34,10 +33,9 @@ runs:
         export CARGO_HOME="${CARGO_HOME:-/usr/local/cargo}"
         export RUSTUP_HOME="${RUSTUP_HOME:-/usr/local/rustup}"
         export PATH="$CARGO_HOME/bin:$PATH"
-        if ! command -v rustup &>/dev/null; then
-          apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
-          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | \
-            sh -s -- -y --default-toolchain none --no-modify-path
+        if ! command -v rustup >/dev/null 2>&1; then
+          echo "::error title=Missing Rust toolchain::rustup is not available in the SimpleKernel dev image. Rebuild the image from .devcontainer/Dockerfile instead of installing Rust in CI."
+          exit 1
         fi
         {
           echo "CARGO_HOME=$CARGO_HOME"
@@ -50,8 +48,8 @@ runs:
       uses: actions/cache@v4
       with:
         path: |
-          ~/.cargo/registry
-          ~/.cargo/git
+          /usr/local/cargo/registry
+          /usr/local/cargo/git
         key: ${{ inputs.cache-key-prefix }}-${{ runner.arch }}-${{ hashFiles('Cargo.lock', 'rust-toolchain.toml') }}
         restore-keys: |
           ${{ inputs.cache-key-prefix }}-${{ runner.arch }}-

.github/workflows/dev-image.yml

@@ -6,12 +6,12 @@ on:
   push:
     branches: [main]
     paths:
-      - '.devcontainer/Dockerfile'
+      - '.devcontainer/**'
       - '.github/workflows/dev-image.yml'
   workflow_dispatch:
 
 env:
-  IMAGE: ghcr.io/simple-xx/simplekernel-dev
+  IMAGE: ghcr.io/simple-xx/simplekernel-devcontainer
 
 jobs:
   build-and-push:

.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
   build-docs:
     runs-on: ubuntu-24.04-arm
     container:
-      image: ghcr.io/simple-xx/simplekernel-dev:latest
+      image: ghcr.io/simple-xx/simplekernel-devcontainer:latest
     steps:
       - uses: actions/checkout@v4
         with:

.github/workflows/workflow.yml

@@ -24,7 +24,7 @@ jobs:
       contents: read
       packages: read
     container:
-      image: ghcr.io/simple-xx/simplekernel-dev:latest
+      image: ghcr.io/simple-xx/simplekernel-devcontainer:latest
     steps:
       - uses: actions/checkout@v4
         with:
@@ -68,9 +68,7 @@ jobs:
         run: cargo test -p memory_types -p config -p page_table_entry
 
       - name: Dependency audit
-        run: |
-          cargo install --locked cargo-deny || true
-          cargo deny check
+        run: cargo deny check
 
   build:
     needs: check
@@ -79,7 +77,7 @@ jobs:
       contents: read
       packages: read
     container:
-      image: ghcr.io/simple-xx/simplekernel-dev:latest
+      image: ghcr.io/simple-xx/simplekernel-devcontainer:latest
     strategy:
       fail-fast: false
       matrix:

AGENTS.md

@@ -32,6 +32,16 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 - **Design overview** → `docs/design/00-概述.md` (master plan — written pre-implementation, may be outdated; code is source of truth)
 - **Phase details** → `docs/design/P0-P7` (implementation plans, all phases complete — may diverge from actual code)
 
+## DOCUMENT ROUTING
+
+- 根 `README.md` 只保留面向普通读者的项目介绍、快速开始、构建/测试入口、项目结构和贡献入口。
+- 目录级规则、协作约定、修改 checklist、验证入口、局部职责边界和不要假设的事项，统一写入最近的 `AGENTS.md`。
+- `docs/AGENTS.md` 是文档目录索引和文档类型路由；`docs/conventions.md` 记录长期工程约定。
+- `docs/adr/AGENTS.md`、`docs/rfcs/AGENTS.md`、`docs/specs/AGENTS.md`、`docs/plans/AGENTS.md` 和 `docs/templates/AGENTS.md` 分别管理对应文档类型。
+- `tests/AGENTS.md`、`xtask/AGENTS.md` 和 crate-local `AGENTS.md` 是各目录的局部运行手册。
+- 新增目录级 README 默认不允许。确实需要新增时，必须确认它是面向仓库外普通读者的入口，并说明为什么不能放入最近的 `AGENTS.md`、设计文档、ADR/RFC、Spec 或 Plan。
+- README 与 `AGENTS.md` 冲突时，以 `AGENTS.md` 为准，并在同一变更中修正冲突。
+
 ## CODE MAP
 | Module | Purpose | Key Files |
 |--------|---------|-----------|
@@ -76,7 +86,8 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 ### Environment
 - **容器优先**：凡是能在 Dev Container / Docker 中完成的构建、检查、`pre-commit`、固件构建、QEMU 运行和系统测试，都应在容器内执行，不要为本项目修改宿主机工具链。
 - **宿主机边界**：宿主机只负责 Docker 或兼容容器运行时、Git、编辑器/AI agent 和已有 Dev Container 入口工具；不要在宿主机安装 Rust nightly、交叉编译器、QEMU、固件构建依赖或其他项目开发依赖来绕过容器。
-- **命令入口**：在宿主机发起命令时优先使用 `devcontainer exec --workspace-folder . <command>`，或使用当前已构建的项目开发镜像运行等价命令。
+- **命令入口**：宿主机先按 `.devcontainer/AGENTS.md` 设置 `DEVCONTAINER_NAME=simplekernel-devcontainer-{username}-{branch}`，再通过 Dev Container CLI 或手动 fallback 启动常驻容器。项目命令优先使用 `docker exec -w /workspace "$DEVCONTAINER_NAME" <command>`；`devcontainer exec --workspace-folder . <command>` 仅作为临时交互入口。
+- **CI 工具链一致性**：CI、Dev Container 和本地容器应使用 `.devcontainer/Dockerfile` 声明的工具链。不要在 workflow 中临时安装 Rust、cargo 子命令、QEMU 或交叉工具链来补齐缺失环境；发现镜像缺工具时，先修复 Dockerfile 或重建开发镜像。
 - **例外**：只有正在修复容器自身配置、文档/Git 等入口操作，或任务明确要求无需项目工具链的本地操作时，才考虑宿主机执行；说明原因并保持宿主/容器步骤边界清晰。
 
 ### Git
@@ -91,6 +102,7 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 - **机器可读格式**：`.json` 文件保持严格 JSON，不写注释、不留尾随逗号；需要说明时写在相邻文档。
 - **文件规模**：手写源码超过 300 行时 review 应检查职责边界；原则上不超过 500 行，超过时 PR 需说明暂不拆分理由或拆分计划。
 - **运行时配置**：FDT、MMIO、timer 频率、core count、QEMU 参数、固件路径和硬件拓扑等运行时/platform 输入必须显式校验；缺失或非法输入应 fail fast，不用 `Default`、`unwrap_or(...)` 等隐式 fallback 掩盖。
+- **目录级文档**：可由局部 `AGENTS.md` 承载的目录说明、模块协作规则、工具运行手册和测试目录索引，不再新增 README。
 
 ### Rust
 - **Language**: Rust nightly, `#![no_std]`, `#![no_main]`, edition 2024
@@ -133,31 +145,44 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 - Cargo workspace: root package (kernel) + `xtask` (build tool)
 
 ## COMMANDS
-宿主机侧执行项目命令时使用 `devcontainer exec --workspace-folder . <command>`。
+宿主机侧先按 SimpleKernel 命名规则设置常驻容器名，再启动 Dev Container：
+
+```bash
+DEVCONTAINER_USER="$(id -un | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+DEVCONTAINER_BRANCH="$(git branch --show-current | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+if [ -z "$DEVCONTAINER_BRANCH" ]; then
+  echo "detached HEAD is not allowed for the devcontainer name" >&2
+  exit 1
+fi
+export DEVCONTAINER_NAME="simplekernel-devcontainer-${DEVCONTAINER_USER}-${DEVCONTAINER_BRANCH}"
+devcontainer up --workspace-folder .
+```
+
+后续项目命令通过同一个常驻容器执行：
 
 ```bash
 # Build kernel
-devcontainer exec --workspace-folder . cargo xtask build --arch riscv64
-devcontainer exec --workspace-folder . cargo xtask build --arch aarch64
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask build --arch riscv64
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask build --arch aarch64
 
 # Run in QEMU (via xtask — handles FIT image + TFTP + QEMU)
-devcontainer exec --workspace-folder . cargo xtask run --arch riscv64 --timeout 30
-devcontainer exec --workspace-folder . cargo xtask run --arch aarch64 --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask run --arch riscv64 --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask run --arch aarch64 --timeout 30
 
 # Debug (GDB on localhost:1234)
-devcontainer exec --workspace-folder . cargo xtask debug --arch riscv64
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask debug --arch riscv64
 
 # System tests in QEMU
-devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --timeout 30
-devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name panic-test --timeout 30
-devcontainer exec --workspace-folder . cargo xtask test --list
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --arch riscv64 --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --arch riscv64 --name panic-test --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --list
 
 # Format + lint check
-devcontainer exec --workspace-folder . cargo fmt --check
-devcontainer exec --workspace-folder . cargo clippy -- -D warnings
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo fmt --check
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo clippy -- -D warnings
 
 # Documentation
-devcontainer exec --workspace-folder . cargo doc --no-deps
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo doc --no-deps
 ```
 
 **QEMU 超时**：在 QEMU 中运行内核或测试时经常出现卡死或无限循环打印日志的情况。所有通过 Bash 工具执行的 QEMU 相关命令（`cargo xtask run`、`cargo xtask test`）**必须设置 30 秒超时**（`timeout: 30000`）。超时后应 `pkill -f qemu-system` 清理残留进程。
@@ -171,9 +196,9 @@ devcontainer exec --workspace-folder . cargo doc --no-deps
 每个测试是独立的 `#![no_std]` 裸机二进制，启动独立 QEMU 实例，拥有干净的内核环境。
 
 ```bash
-devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --timeout 30
-devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name frame-test/alloc --timeout 30
-devcontainer exec --workspace-folder . cargo xtask test --list
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --arch riscv64 --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --arch riscv64 --name frame-test/alloc --timeout 30
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --list
 ```
 
 测试基础设施位于 `tests/test_harness/`，核心是 `test_main!` 宏：
@@ -250,6 +275,7 @@ test_harness::test_main!(simplekernel::boot::InitLevel::Full, run_test, should_p
 - **Session Prompt**（输出格式参考）: `docs/audit/review-session-prompt.md`
 - **ADR 目录**（架构决策记录）: `docs/adr/`
 - **ADR 模板**: `docs/templates/adr-template.md`
+- **文档目录入口**: `docs/AGENTS.md`
 
 ### 审计工作流
 

CONTRIBUTING.md

@@ -9,17 +9,24 @@
 开发环境默认使用 Dev Container。宿主机只保留 Docker 或兼容容器运行时、Git、编辑器/AI agent 和已有 Dev Container 入口工具；不要为了本项目在宿主机安装 Rust nightly、交叉编译器、QEMU、固件构建依赖或其他项目开发依赖。
 
 ```bash
+DEVCONTAINER_USER="$(id -un | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+DEVCONTAINER_BRANCH="$(git branch --show-current | sed -E 's/[^[:alnum:]_.-]+/-/g; s/^-+//; s/-+$//')"
+if [ -z "$DEVCONTAINER_BRANCH" ]; then
+  echo "detached HEAD is not allowed for the devcontainer name" >&2
+  exit 1
+fi
+export DEVCONTAINER_NAME="simplekernel-devcontainer-${DEVCONTAINER_USER}-${DEVCONTAINER_BRANCH}"
 devcontainer up --workspace-folder .
-devcontainer exec --workspace-folder . bash
+docker exec -w /workspace "$DEVCONTAINER_NAME" bash
 ```
 
 宿主机侧常用命令：
 
 ```bash
-devcontainer exec --workspace-folder . cargo xtask build --arch riscv64
-devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
-devcontainer exec --workspace-folder . cargo fmt --check
-devcontainer exec --workspace-folder . cargo clippy -- -D warnings
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask build --arch riscv64
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo xtask test --arch riscv64
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo fmt --check
+docker exec -w /workspace "$DEVCONTAINER_NAME" cargo clippy -- -D warnings
 ```
 
 通过 Bash 工具运行 QEMU 相关命令时必须设置 30 秒超时；超时后清理残留 QEMU 进程。
@@ -37,11 +44,11 @@ devcontainer exec --workspace-folder . cargo clippy -- -D warnings
 
 | 改动 | 必须同步检查 |
 |------|--------------|
-| 启动流程、命令、测试入口变化 | `README.md`、`docs/README.md`、相关设计或计划文档 |
+| 启动流程、命令、测试入口变化 | 根 `README.md`、`docs/AGENTS.md`、相关局部 `AGENTS.md`、相关设计或计划文档 |
 | 架构不变量变化 | `docs/adr/`、SAD/SDD、`AGENTS.md` |
 | 项目长期约定、Copyright、注释、文件规模、运行时配置规则变化 | `AGENTS.md`、`docs/conventions.md` |
 | Git/commit/DCO/提交模板变化 | `AGENTS.md`、`README.md`、本文件、`.gitmessage`、PR 模板 |
-| 公开 trait、错误码、类型或模块边界变化 | 代码文档注释、SDD、模块 README |
+| 公开 trait、错误码、类型或模块边界变化 | 代码文档注释、SDD、最近的局部 `AGENTS.md` |
 | 固件、第三方源码或外部交付物变化 | `3rd/` 记录、`README.md`、相关 ADR/设计/审计文档 |
 | QEMU、固件链路或目标平台假设变化 | `README.md`、相关设计文档、相关测试说明 |