feat: add portable fp review skill installer

1

2026-06-27 1ce0fd70b0d398b5a226a70f10fd5fc065a620fd

feat: add portable fp review skill installer

 skill/复盘/AI协作复盘规范.md

New file
@@ -0,0 +1,321 @@
# AI协作复盘规范

文件职责：定义 AI 协作过程中出现漏发现、误放行、反复返修、职责混乱、消息断链或流程失效时，如何发起复盘、保留事实链、分析根因、形成可落地方案并完成复审。
管理规范/模板：`../../全局规范.md`；`../../common/project-doc/项目规范.md`。
引用文件：各项目本地规范、对应体系规范、事项总纲、事项设计或计划、执行日志、审计报告、问题记录、项目问题反馈。
记录方式：全局技能规范；复盘口径变化时更新本文，并同步相关目录导读或技能入口。

## 1. 定位

AI 协作复盘不是普通聊天讨论，也不是单次返修记录。

它用于处理“协作流程本身出了问题”的场景，目标是找到为什么问题会发生、为什么执行或审核没有挡住、如何防止复发，并把结果落到可执行的流程、规范、代码、数据、问题关闭或责任边界中。

复盘必须有结果。结果可以是：

1. 修改协作流程、审核流程或工作说明。
2. 修改全局规范、项目规范、体系规范或本地规范。
3. 修复某个代码 bug、数据 bug、需求 bug、脚本 bug 或文档口径问题。
4. 补齐缺失证据链、执行日志、审计报告、问题记录或结果包。
5. 明确某个事项降读、暂停、重跑、返修、关闭或不再扩展。
6. 输出完整解决方案，交给对应角色执行并复审。

禁止只做解释，不形成后续动作或明确关闭依据。

## 2. 触发条件与启动权限

当前阶段，AI 协作复盘默认由用户或项目管理员正式触发。

AI、执行员、审核员发现以下情况时，可以提出“建议启动复盘”，并说明原因、影响范围和建议复盘边界；但不得自行把普通问题升级为正式复盘流程。

出现以下任一情况，可以建议启动 AI 协作复盘：

1. 用户、同事、执行员、审核员或其他 AI 发现已经走完流程后仍漏掉关键问题。
2. 审核误放行，后续才发现设计、执行、数据、代码、证据链或结论存在实质问题。
3. 同一问题反复返修后仍重复出现，通常大于等于 3 次。
4. 执行员只局部修补，未处理问题根因，导致新包、新文档、新代码中复发。
5. 审核员只看送审对象，没有回到来源聊天、原始反馈、总纲、设计、执行日志或历史问题。
6. 执行员和审核员职责边界混乱，例如审核员代替执行员改主产物，或执行员把自检冒充审核结论。
7. 消息、handoff、inbox、可见投递或 ack 断链，导致事项没有明确回复、blocker、ack 或关闭状态。
8. 问题记录、审计报告、执行日志、总纲、设计或结果包之间状态不一致。
9. 用户明确要求复盘，或用户指出“为什么前面没发现 / 为什么反复修不好”。

正式启动条件：

1. 用户明确要求复盘。
2. 项目管理员确认启动复盘。
3. 用户授权某个审核员或管理角色代为启动某类复盘。

未正式启动前，AI 可以做初步事实整理和风险提示，但不得要求执行员按复盘全流程返工，也不得把事项状态改成“复盘中”。

## 3. 复盘原则

1. 找真正原因，不只解释表面错误。
2. 同时检查执行侧、审核侧、规范侧和协作侧。
3. 复盘必须形成可执行结论，不能只停留在聊天。
4. 不层层加码，只针对已经暴露的真实风险补必要机制。
5. 复盘强调解决关键问题，不是吹毛求疵，也不是把简单事项改造成重流程。
6. 不自动推翻未受影响的已审核结果；只有影响目标、证据、结论、主流程或下游使用时，才要求重跑或降读。
7. 复盘中发现规范冲突或规范不清楚，应标为规范问题，不能强行按个人理解加规则。
8. 复盘完成前，不得把相关事项标记为已彻底关闭，除非关闭条件已经被复审确认。

## 4. 角色分工

| 角色 | 职责 |
|---|---|
| 发起人 | 提出复盘触发问题，提供原始反馈或问题描述，接收最终摘要 |
| 执行员 | 整理执行事实链、承认执行侧缺口、提出或执行返修动作 |
| 审核员 | 独立复核事实链、确认审核侧是否漏审、审核复盘方案和落地结果 |
| 项目管理员 | 处理跨角色、权限、流程、工作空间、长期反复问题或项目级协调 |
| 规范维护员 / 体系维护员 | 在被授权时修改对应规范、模板、创建指南或体系流程 |

职责边界：

1. 执行员负责业务返修和主产物修复。
2. 审核员负责指出阻断项、审计结论、复审和审核职责内文档维护。
3. 审核员不得默认代替执行员修改被审主产物。
4. 如需修改被审体系执行规范，应创建规范维护事项，或由项目配置清单额外授权。

## 5. 标准流程

### 5.1 登记复盘事项

复盘开始前，必须在对应项目或体系的问题记录、事项总纲、审计报告或项目问题反馈中建立入口。

最低记录：

1. 复盘 ID。
2. 触发来源。
3. 原始反馈或问题描述。
4. 关联事项 ID、run ID、审计 ID、消息 ID 或文档路径。
5. 初步影响范围。
6. 当前状态。

### 5.2 保留原始反馈

必须保留原始反馈或准确引用入口。

如果反馈来自聊天、同事意见、审核意见或用户追问，应尽量保留原文、消息 ID、时间、附件路径或截图入口。不得只保留压缩摘要后直接做结论。

### 5.3 收集事实链

事实链至少覆盖：

1. 原始目标或来源聊天要求是什么。
2. 设计或计划怎么写。
3. 执行员实际做了什么。
4. 审核员审了什么、没审什么、给了什么结论。
5. 问题最早在哪一步出现。
6. 问题为什么没有在执行或审核中被挡住。
7. 相关文档、结果包、脚本、数据、图片、日志、审计报告和消息 ID。

### 5.4 拆问题清单

问题必须分层，不得只写“流程有问题”。

至少拆成：

1. 直接问题：实际错了什么。
2. 执行员问题：执行为什么没挡住。
3. 审核员问题：审核为什么没挡住。
4. 规范 / 体系问题：规范、模板、创建指南、流程、字段、证据链哪里缺。
5. 协作问题：消息、handoff、ack、角色边界、权限或工作空间哪里断。
6. 发起人沟通问题：是否没有向用户说明状态、边界、剩余问题或下一步。
7. 残余风险：还有哪些风险没有覆盖。

### 5.5 根因判断

每个问题至少追到一个可修复根因。

常见根因：

1. 原始反馈没有原子化成清单。
2. 设计或计划没有覆盖完整目标。
3. 执行日志只写结果，没写关键节点。
4. 审核只看当前产物，没回到来源聊天和设计。
5. 历史问题没有转成回归检查项。
6. 自检只覆盖机器一致性，没覆盖人工可读性或业务语义。
7. 多个模块各自修补，没有抽公共入口或公共规则。
8. 权限和职责边界不清。
9. 消息处理没有到回复、blocker、ack 或关闭状态。

### 5.6 制定系统性方案

方案必须回答：

1. 改什么：文档、流程、规范、代码、数据、结果包、测试、校验、工作说明或权限。
2. 谁改：执行员、审核员、项目管理员、规范维护员或代码维护员。
3. 怎么验：设计审核、执行复审、回归测试、样本复算、人工抽查、证据链检查或结果包对照。
4. 何时关闭：关闭条件、复审入口、允许引用的结论边界。
5. 是否影响已有结论：不影响、降读、暂停引用、需要重跑或需要重新审核。

方案不得只写“需要修复”。复杂问题应给出可直接执行的修复方案；简单问题可以给最小必要修正。

### 5.6A 需要用户或项目管理员裁定时的提问规则

复盘过程中，如遇到无法通过现有文档、证据、日志、代码或权限自行解决的问题，可以向用户或项目管理员提问。

提问前必须先说明：

1. 已经查过哪些证据。
2. 当前卡在哪个关键判断。
3. 为什么该判断必须由用户或项目管理员裁定。
4. 不裁定会影响什么。
5. 可选方案和各自影响。

只有以下情况适合提问：

1. 原始要求缺失或互相冲突，且会影响复盘结论。
2. 关键业务口径只能由用户裁定。
3. 权限、角色、责任边界冲突需要项目管理员决定。
4. 多个修复方案都会改变目标、范围、成本或结论边界。
5. 继续执行可能覆盖证据、扩大损失或误导下游。

不得因为低影响命名、格式、表达、轻微路径说明、个人偏好或可自行查证的问题频繁打扰用户。

### 5.7 方案审核

复盘方案必须由对应审核员或项目管理员审核。

审核重点：

1. 是否覆盖触发反馈。
2. 是否同时检查执行侧和审核侧。
3. 根因是否能解释问题复发。
4. 方案是否能防止同类问题再次发生。
5. 是否不必要加码。
6. 是否有清晰关闭条件。

方案审核通过前，不得把复盘结论写成已完成。

### 5.8 落地执行

方案通过后，按责任分工落地。

落地可能包括：

1. 修改规范、流程、模板、创建指南或工作说明。
2. 修代码、补公共函数、补测试或补脚本。
3. 重跑结果包、补证据、补图、补账本或修复数据。
4. 更新问题记录、执行日志、审计报告、总纲或设计状态。
5. 向相关 AI 发消息，要求按新流程执行。

### 5.9 落地复审

落地完成后必须复审。

复审至少确认：

1. 原问题是否关闭。
2. 是否产生新问题。
3. 状态账本是否同步。
4. 关联文档和证据入口是否可追踪。
5. 关闭条件是否满足。
6. 是否需要把问题升级给项目管理员。

### 5.10 向发起人输出摘要

复盘结束后，必须给发起人一个简明摘要。

摘要至少包含：

1. 发现了哪些问题。
2. 为什么会漏发现或反复出现。
3. 已经改了什么。
4. 还保留什么边界。
5. 后续同类问题走什么流程。
6. 当前事项是否允许关闭、引用、继续执行或需要重跑。

## 6. 输出格式

复盘记录建议使用以下结构：

```text
复盘 ID：
触发来源：
关联事项：
原始反馈入口：
当前状态：

问题清单：
1. 直接问题
2. 执行侧问题
3. 审核侧问题
4. 体系 / 规范问题
5. 协作 / 消息问题
6. 残余风险

根因：
1. ...

解决方案：
1. 改什么
2. 谁负责
3. 如何验证
4. 关闭条件

落地记录：
1. ...

复审结论：
通过 / 不通过 / HELD

发起人摘要：
...
```

## 7. 验收标准

复盘通过必须同时满足：

1. 原始反馈和触发原因可追踪。
2. 问题清单覆盖直接问题、执行侧、审核侧、体系侧和协作侧。
3. 每个关键问题都有根因。
4. 每个根因都有解决方案或明确降读 / 暂停 / 不处理理由。
5. 方案已经落地到对应文档、代码、数据、流程、权限或问题记录。
6. 落地结果已经复审。
7. 发起人摘要已经输出。
8. 关闭条件已满足，或明确保持 HELD / 暂停 / 待重跑。

## 8. 不层层加码边界

复盘的目标是解决关键问题、修复流程断点、防止真实风险复发。不得把复盘变成形式化负担，也不得为了“看起来更完整”不断追加与触发问题无关的校验、文档、重跑或审核。

1. 复盘不自动要求重跑所有历史产物。
2. 复盘不自动推翻未受影响的已审核结论。
3. 只影响阅读入口的问题，不扩大为业务规则重审。
4. 只影响单个局部文件的问题，不扩大为全体系重构。
5. 新增审核项必须说明针对哪个真实风险。
6. 如果只是低影响命名、格式、表达差异，不作为阻断问题。

## 9. 和现有体系的关系

AI 协作复盘是跨体系能力，不替代各体系正常审核。

默认关系：

```text
正常事项审核发现问题 -> 写入对应审计报告
问题需要跨轮跟踪 -> 在问题记录中建索引
同类问题反复、漏审、误放行、协作断链 -> 启动 AI 协作复盘
```

复盘结论应落回原体系，不另起孤岛。

例如：

1. 实验问题落回实验总纲、实验执行日志、实验审计报告或实验问题记录。
2. 需求问题落回需求总纲、需求设计、需求审计报告或需求问题记录。
3. 开发问题落回开发事项总纲、开发执行日志、开发审计报告或代码问题记录。
4. 案例问题落回案例总纲、案例执行日志、案例审计报告或案例问题记录。
5. 项目协作问题落回项目事项、项目问题记录或 AI 工作空间的项目问题反馈。

## 10. 禁止事项

1. 禁止只解释原因但不形成结果。
2. 禁止把复盘当成普通聊天，不登记入口、不留事实链。
3. 禁止只复盘执行员，不复盘审核员和体系。
4. 禁止审核员用复盘名义直接改被审主产物。
5. 禁止把未复审的方案说成已闭环。
6. 禁止把局部问题扩大成全流程重跑，除非影响目标、证据、结论或主链。
7. 禁止用“已修复”替代关闭条件和复审结论。

 skill/复盘/SKILL.md

New file
@@ -0,0 +1,20 @@
---
name: fp
description: Use for AI collaboration postmortem / 复盘 when a user or project admin asks to review missed issues, mistaken approval, repeated rework, unclear responsibility boundaries, broken message handoff, or failed AI collaboration workflow, and produce a result that lands in workflow, docs, code, data, evidence, or closure.
---

# fp - AI协作复盘

Use this skill when the user explicitly asks for `fp`、复盘、协作复盘、流程复盘，或追问为什么问题漏发现、为什么审核误放行、为什么反复修不好、为什么消息或角色协作断链。

Before acting, read `AI协作复盘规范.md` in this skill directory completely.

Core rules:

1. Formal postmortem starts only when the user or project admin triggers it.
2. AI may suggest a postmortem, but must not upgrade ordinary issues into formal postmortem by itself.
3. The postmortem must have an outcome: workflow, docs, code, data, evidence, closure, downgrade, rerun, or assigned fix.
4. Check executor side, reviewer side, governance side, and collaboration/message side.
5. Do not over-escalate or add unnecessary process burden.
6. Ask the user only when a real blocking decision cannot be resolved from documents, evidence, logs, code, permissions, or project configuration.
7. Keep large evidence in files; show only summaries, file paths, message IDs, and key proof entries in the Codex window.

 skill/复盘/install-fp-skill.ps1

New file
@@ -0,0 +1,165 @@
param(
    [string]$SkillsRoot,
    [switch]$InstallAllDetected,
    [switch]$UseWorkspaceLock,
    [switch]$WhatIf
)

$ErrorActionPreference = "Stop"

$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
$WorkspaceRoot = Resolve-Path (Join-Path $ScriptDir "..\..")

$SourceSkill = Join-Path $ScriptDir "SKILL.md"
$SourceSpecItem = Get-ChildItem -LiteralPath $ScriptDir -File -Filter "AI*.md" |
    Where-Object { $_.Name -ne "SKILL.md" } |
    Select-Object -First 1
if (-not $SourceSpecItem) {
    throw "Missing source spec: expected an AI*.md file beside install-fp-skill.ps1"
}
$SourceSpec = $SourceSpecItem.FullName

if (-not (Test-Path -LiteralPath $SourceSkill)) {
    throw "Missing source SKILL.md: $SourceSkill"
}
if (-not (Test-Path -LiteralPath $SourceSpec)) {
    throw "Missing source spec: $SourceSpec"
}

function Get-LockedSkillsRoot {
    $SkillLock = Join-Path $WorkspaceRoot.Path ".mbx\skills.lock.yaml"
    if (-not (Test-Path -LiteralPath $SkillLock)) {
        return $null
    }
    $LockedTargetLine = Get-Content -LiteralPath $SkillLock -Encoding UTF8 |
        Where-Object { $_ -match "^\s*target_dir:\s*(.+?)\s*$" } |
        Select-Object -First 1
    if ($LockedTargetLine -and $LockedTargetLine -match "^\s*target_dir:\s*(.+?)\s*$") {
        return $Matches[1].Trim().Trim("'").Trim('"')
    }
    return $null
}

function Test-CurrentUserPath {
    param([string]$Path)
    if (-not $Path -or $Path.Trim() -eq "") {
        return $false
    }
    $homePath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($HOME)
    return $Path.StartsWith($homePath, [System.StringComparison]::OrdinalIgnoreCase)
}

function Add-Target {
    param(
        [System.Collections.ArrayList]$Targets,
        [string]$Path,
        [string]$Reason,
        [bool]$AllowForeign = $false
    )
    if (-not $Path -or $Path.Trim() -eq "") {
        return
    }
    $resolved = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path)
    if (-not $AllowForeign -and -not (Test-CurrentUserPath -Path $resolved)) {
        [void]$SkippedTargets.Add([ordered]@{
            skills_root = $resolved
            reason = $Reason
            skipped_reason = "foreign_user_absolute_path"
        })
        return
    }
    foreach ($target in $Targets) {
        if ($target.skills_root -eq $resolved) {
            return
        }
    }
    [void]$Targets.Add([ordered]@{
        skills_root = $resolved
        reason = $Reason
    })
}

$Targets = New-Object System.Collections.ArrayList
$SkippedTargets = New-Object System.Collections.ArrayList
$LockedTarget = Get-LockedSkillsRoot

if ($SkillsRoot -and $SkillsRoot.Trim() -ne "") {
    Add-Target -Targets $Targets -Path $SkillsRoot -Reason "explicit -SkillsRoot" -AllowForeign $true
} elseif ($InstallAllDetected) {
    if ($env:CODEX_HOME -and $env:CODEX_HOME.Trim() -ne "") {
        Add-Target -Targets $Targets -Path (Join-Path $env:CODEX_HOME "skills") -Reason "CODEX_HOME"
    }
    if ($LockedTarget) {
        Add-Target -Targets $Targets -Path $LockedTarget -Reason ".mbx skills.lock target_dir" -AllowForeign ([bool]$UseWorkspaceLock)
    }
    Add-Target -Targets $Targets -Path (Join-Path $HOME ".codex\skills") -Reason "current user .codex"
    Add-Target -Targets $Targets -Path (Join-Path $HOME ".codex3\skills") -Reason "current user .codex3"
    Get-ChildItem -LiteralPath $HOME -Directory -Force -ErrorAction SilentlyContinue |
        Where-Object { $_.Name -like ".codex*" -and (Test-Path -LiteralPath (Join-Path $_.FullName "skills")) } |
        ForEach-Object { Add-Target -Targets $Targets -Path (Join-Path $_.FullName "skills") -Reason "detected existing Codex home" }
} else {
    if ($env:CODEX_HOME -and $env:CODEX_HOME.Trim() -ne "") {
        Add-Target -Targets $Targets -Path (Join-Path $env:CODEX_HOME "skills") -Reason "CODEX_HOME"
        if ($LockedTarget -and (Test-CurrentUserPath -Path $LockedTarget)) {
            Add-Target -Targets $Targets -Path $LockedTarget -Reason ".mbx skills.lock target_dir"
        }
    } elseif ($LockedTarget -and (Test-CurrentUserPath -Path $LockedTarget)) {
        Add-Target -Targets $Targets -Path $LockedTarget -Reason ".mbx skills.lock target_dir"
    } elseif (Test-Path -LiteralPath (Join-Path $HOME ".codex\skills")) {
        Add-Target -Targets $Targets -Path (Join-Path $HOME ".codex\skills") -Reason "current user existing .codex"
    } elseif (Test-Path -LiteralPath (Join-Path $HOME ".codex3\skills")) {
        Add-Target -Targets $Targets -Path (Join-Path $HOME ".codex3\skills") -Reason "current user existing .codex3"
    } else {
        Add-Target -Targets $Targets -Path (Join-Path $HOME ".codex\skills") -Reason "default current user .codex"
    }
}

if ($Targets.Count -eq 0) {
    throw "No safe target skills directory resolved. Pass -SkillsRoot explicitly, or use -UseWorkspaceLock if you intentionally want the workspace lock target."
}

$result = [ordered]@{
    workspace_root = $WorkspaceRoot.Path
    source_skill = $SourceSkill
    source_spec = $SourceSpec
    codex_home = $env:CODEX_HOME
    install_all_detected = [bool]$InstallAllDetected
    use_workspace_lock = [bool]$UseWorkspaceLock
    what_if = [bool]$WhatIf
    targets = $Targets
    skipped_targets = $SkippedTargets
}

if ($WhatIf) {
    $result.status = "DRY_RUN"
    $result.note = "No files copied. Review targets before installing."
    $result | ConvertTo-Json -Depth 6
    exit 0
}

$installed = New-Object System.Collections.ArrayList
foreach ($target in $Targets) {
    $targetRoot = $target.skills_root
    $TargetDir = Join-Path $targetRoot "fp"
    New-Item -ItemType Directory -Force -Path $TargetDir | Out-Null
    Copy-Item -LiteralPath $SourceSkill -Destination (Join-Path $TargetDir "SKILL.md") -Force
    Copy-Item -LiteralPath $SourceSpec -Destination (Join-Path $TargetDir $SourceSpecItem.Name) -Force

    $installedSkill = Join-Path $TargetDir "SKILL.md"
    $installedSpec = Join-Path $TargetDir $SourceSpecItem.Name
    $frontmatter = Get-Content -LiteralPath $installedSkill -Encoding UTF8 | Select-Object -First 4
    if ($frontmatter[0] -ne "---" -or $frontmatter[1] -notmatch "^name:\s*fp\s*$" -or $frontmatter[2] -notmatch "^description:\s+") {
        throw "Installed SKILL.md frontmatter is invalid: $installedSkill"
    }
    [void]$installed.Add([ordered]@{
        skills_root = $targetRoot
        target_dir = $TargetDir
        reason = $target.reason
        files = @($installedSkill, $installedSpec)
    })
}

$result.status = "INSTALLED"
$result.installed = $installed
$result.note = "Restart or reopen target Codex sessions before expecting fp to appear in the skill list. Existing threads may still need explicit local skill routing."
$result | ConvertTo-Json -Depth 6

 skill/复盘/复盘技能安装指南.md

New file
@@ -0,0 +1,182 @@
# 复盘技能安装指南

文件职责：说明体系管理员如何把 `AI协作复盘规范.md` 安装成本机 Codex 技能。
管理规范/模板：`../../全局规范.md`；`../../skill/复盘/AI协作复盘规范.md`。
引用文件：`AI协作复盘规范.md`。
记录方式：技能安装指南；安装方式变化时更新本文。

## 1. 技能定位

技能名称建议：

```text
fp
```

`fp` 是“复盘”的缩写，用于触发 AI 协作复盘流程。

安装后，当用户明确提到：

```text
fp
复盘
协作复盘
流程复盘
为什么反复修不好
为什么前面没发现
漏审 / 误放行 / 反复返修
```

AI 应优先按 `AI协作复盘规范.md` 工作。

注意：当前阶段，正式复盘仍由用户或项目管理员触发。AI 可以建议启动复盘，但不得自行把普通问题升级为正式复盘。

## 2. 安装结果

安装完成后，本机应存在：

```text
<Codex技能目录>/fp/SKILL.md
<Codex技能目录>/fp/AI协作复盘规范.md
```

其中：

1. `SKILL.md` 是 Codex 识别技能的入口。
2. `AI协作复盘规范.md` 是技能执行时必须阅读和遵守的完整规范。
3. `skill/复盘/install-fp-skill.ps1` 是本仓库提供的安装脚本，用于把上述两个文件复制到目标 Codex 技能目录。

## 3. 技能目录识别规则

当前机器可能同时存在 `.codex`、`.codex2`、`.codex3` 等多个 Codex home。安装前必须确认目标会话实际使用哪个技能目录。

默认规则：

1. 如果显式传入 `-SkillsRoot`，安装到该目录。
2. 如果当前 PowerShell 设置了 `$env:CODEX_HOME`，安装到 `$env:CODEX_HOME\skills`。
3. 如果当前工作区存在 `.mbx/skills.lock.yaml` 且其中 `target_dir` 属于当前用户目录，也同时安装到该目录。
4. 如果以上都没有，优先使用当前用户已有的 `$HOME\.codex\skills` 或 `$HOME\.codex3\skills`。
5. 如果需要覆盖当前用户下多个 Codex home，使用 `-InstallAllDetected`。

安全边界：

1. 默认不会使用其他用户目录下的绝对路径，例如从 Git 拉下来的 `.mbx/skills.lock.yaml` 如果仍写着 `C:\Users\Administrator\...`，在同事机器上会被跳过。
2. 只有明确传 `-SkillsRoot`，或传 `-UseWorkspaceLock`，脚本才会允许使用非当前用户目录的目标路径。
3. 安装前应先运行 `-WhatIf` 预览目标目录。

常见目标：

```text
C:\Users\<用户名>\.codex3\skills\fp
```

不要只因为本机存在 `.codex`、`.codex3` 或 session 文件在某个目录下，就判断技能目录也在那里。MB-X 托管会话应优先以 `.mbx/skills.lock.yaml` 的 `target_dir` 为准；必要时同时检查目标窗口实际技能列表。

## 4. 安装步骤

在 PowerShell 中进入管理系统根目录：

```powershell
Set-Location D:\manage_system
```

默认安装：

```powershell
.\skill\复盘\install-fp-skill.ps1
```

安装前预览目标路径：

```powershell
.\skill\复盘\install-fp-skill.ps1 -WhatIf
```

显式安装到指定技能根目录：

```powershell
.\skill\复盘\install-fp-skill.ps1 -SkillsRoot "C:\Users\<用户名>\.codex3\skills"
```

安装到当前用户下检测到的多个 Codex home：

```powershell
.\skill\复盘\install-fp-skill.ps1 -InstallAllDetected
```

同事从 Git 拉取后的推荐流程：

```powershell
Set-Location <同事本机的 manage_system 路径>
.\skill\复盘\install-fp-skill.ps1 -InstallAllDetected -WhatIf
.\skill\复盘\install-fp-skill.ps1 -InstallAllDetected
```

## 5. 校验步骤

检查文件是否存在：

```powershell
$SkillDir = Join-Path $HOME ".codex3\skills\fp"
Test-Path (Join-Path $SkillDir "SKILL.md")
Test-Path (Join-Path $SkillDir "AI协作复盘规范.md")
```

检查 `SKILL.md` frontmatter：

```powershell
Get-Content -LiteralPath (Join-Path $SkillDir "SKILL.md") -Encoding UTF8 | Select-Object -First 8
```

应能看到：

```text
---
name: fp
description: ...
---
```

重启或新开目标 Codex 会话后，技能列表中应出现 `fp`。已经打开的旧 thread 可能不会自动更新 `Available skills` 列表；此时应按工作说明读取本地 `fp/SKILL.md`，不要仅凭列表缺失判断没有安装。

如果目标窗口没有出现 `fp`，优先检查：

1. 该窗口实际使用的 Codex home 是否与安装目标一致。
2. `fp/SKILL.md` 的 frontmatter 是否包含 `name: fp` 和 `description:`。
3. 窗口是否已经重启或重新打开。
4. 是否安装到了 `.codex` 但目标窗口实际使用 `.codex3`，或反过来。
5. 该窗口是否是安装前创建的旧 thread；旧 thread 可按本地技能文件路径读取使用，但初始 `Available skills` 列表不会自动改写。

## 6. 使用方式

用户可以直接说：

```text
用 fp 复盘一下这个问题为什么反复没修好
```

或：

```text
fp：这次审核为什么没发现问题，按复盘流程走
```

AI 应先读取 `AI协作复盘规范.md`，再按规范执行。

## 7. 更新方式

当 `skill/复盘/AI协作复盘规范.md` 更新后，体系管理员需要重新复制到本机技能目录：

```powershell
Set-Location D:\manage_system
.\skill\复盘\install-fp-skill.ps1
```

如果 `SKILL.md` 的触发词或描述需要更新，应先修改 `skill/复盘/SKILL.md`，再重新执行安装脚本。不要只改已安装目录中的副本。

## 8. 安装边界

1. 安装 `fp` 只提供 AI 执行规范，不会自动修改任何项目文件。
2. 安装 `fp` 不代表所有问题都自动进入复盘；正式复盘仍需用户或项目管理员触发。
3. `fp` 不替代实验审核、需求审核、代码审核、案例审核等体系审核，只在协作流程失效、漏审、误放行、反复返修等场景下使用。
4. 如果复盘需要修改正式规范、代码或结果包，仍必须遵守对应项目和体系的权限、审核和记录要求。

 skill/目录导读.md

New file
@@ -0,0 +1,15 @@
# skill 目录导读

文件职责：记录管理系统下全局技能规范和可复用工作流入口。
管理规范/模板：`../全局规范.md`；`../体系说明.md`。
引用文件：`../管理系统说明.md`；`../全局规范.md`。
记录方式：目录导读；新增、删除或调整技能规范目录时同步更新。

## 技能规范入口

| 目录 / 文件 | 作用 |
|---|---|
| `复盘/AI协作复盘规范.md` | 定义 AI 协作流程失效、漏审、误放行、反复返修、消息断链等问题的复盘流程和落地闭环 |
| `复盘/SKILL.md` | Codex 技能 `fp` 的正式入口模板，用于安装到本机 skills 目录 |
| `复盘/install-fp-skill.ps1` | 将复盘技能安装或更新到目标 Codex skills 目录的 PowerShell 脚本 |
| `复盘/复盘技能安装指南.md` | 说明体系管理员如何把复盘规范安装成本机 Codex 技能 `fp` |

 管理执行日志.md

@@ -106,6 +106,85 @@

当前状态：完成源端可用范围同步

## 2026-06-26 23:55:00 MGMT-SKILL-20260626-FP-INSTALL

关联事项：全局复盘技能安装规范补齐

执行人员：management

动作类型：技能规范补齐 / 本机技能安装

执行目标：补齐 `skill/复盘` 下复盘技能的正式 Codex 入口模板和安装脚本，降低多 Codex home 环境下装错目录的风险。

执行过程：

1. 新增 `skill/复盘/SKILL.md`，作为 Codex 技能 `fp` 的正式入口模板。
2. 新增 `skill/复盘/install-fp-skill.ps1`，优先使用 `$env:CODEX_HOME\skills`，否则默认 `$HOME\.codex3\skills`，并支持 `-SkillsRoot` 显式指定目标。
3. 更新 `skill/复盘/复盘技能安装指南.md`，将手工 heredoc 安装改为脚本安装，并补充多 Codex home、重启窗口和排错说明。
4. 更新 `skill/目录导读.md`，补充 `SKILL.md` 模板和安装脚本入口。
5. 执行安装脚本预览和实际安装；预览时发现 PowerShell 5 对脚本内中文文件名解析会乱码，已将脚本改为按 `AI*.md` 自动发现规范文件，避免硬编码中文文件名。

使用命令或 skill：`skill-creator`；`mbx-file-governance`；`powershell.exe -ExecutionPolicy Bypass -File D:\manage_system\skill\复盘\install-fp-skill.ps1`

关键输出：

- 安装目标：`C:\Users\Administrator\.codex3\skills\fp`
- 已安装文件：`SKILL.md`、`AI协作复盘规范.md`
- `SKILL.md` frontmatter 校验通过：包含 `name: fp` 和 `description:`

异常 / 偏离：已打开的 Codex 角色窗口不会自动加载新技能；需要重启或重新打开目标窗口后，技能列表才会出现 `fp`。

当前状态：完成

## 2026-06-27 01:35:00 MGMT-SKILL-20260627-FP-PORTABLE-INSTALL

关联事项：复盘技能跨机器安装修复

执行人员：management

动作类型：技能安装脚本修复 / 安装指南更新

执行目标：修复 `fp` 复盘技能安装脚本，确保仓库推送到 Git 后，同事在不同用户名、不同 Codex home、不同 MB-X lock 状态下也能安全安装。

执行过程：

1. 修改 `skill/复盘/install-fp-skill.ps1`：
   - 支持 `-SkillsRoot` 显式指定目标 skills 目录。
   - 支持 `-InstallAllDetected` 安装到当前用户下检测到的多个 Codex home。
   - 支持 `-UseWorkspaceLock`，仅在明确指定时允许使用非当前用户目录的 `.mbx/skills.lock.yaml target_dir`。
   - 默认不再盲信仓库中其他机器的绝对路径；如果 lock 指向非当前用户目录，会跳过并在 JSON 结果里记录 `foreign_user_absolute_path`。
   - 默认会同时覆盖当前 `$env:CODEX_HOME\skills` 和当前用户目录下的 MB-X lock target。
2. 更新 `skill/复盘/复盘技能安装指南.md`：
   - 补充跨机器安装规则。
   - 补充同事从 Git 拉取后的推荐命令：先 `-InstallAllDetected -WhatIf`，再执行 `-InstallAllDetected`。
   - 补充旧 thread 的 `Available skills` 不自动改写，需要按本地 `fp/SKILL.md` 路由读取的说明。
3. 在当前机器回归执行：
   - `powershell.exe -ExecutionPolicy Bypass -File D:\manage_system\skill\复盘\install-fp-skill.ps1 -WhatIf`
   - `powershell.exe -ExecutionPolicy Bypass -File D:\manage_system\skill\复盘\install-fp-skill.ps1 -InstallAllDetected -WhatIf`
   - `powershell.exe -ExecutionPolicy Bypass -File D:\manage_system\skill\复盘\install-fp-skill.ps1`

关键输出：

- 默认安装目标已包含：
  - `C:\Users\Administrator\.codex3\skills`
  - `C:\Users\Administrator\.codex\skills`
- 当前机器已安装：
  - `C:\Users\Administrator\.codex3\skills\fp\SKILL.md`
  - `C:\Users\Administrator\.codex\skills\fp\SKILL.md`
- `SKILL.md` frontmatter 校验通过：包含 `name: fp` 和 `description:`。

给同事的安装命令：

```powershell
Set-Location <同事本机的 manage_system 路径>
.\skill\复盘\install-fp-skill.ps1 -InstallAllDetected -WhatIf
.\skill\复盘\install-fp-skill.ps1 -InstallAllDetected
```

异常 / 偏离：旧 Codex thread 的初始 `Available skills` 列表不会自动改写；安装后如果旧窗口仍不显示 `fp`，应按工作说明读取本地 `fp/SKILL.md`，或新建 thread 获取新的系统技能列表。

当前状态：完成

## 2026-06-23 20:46:00 MGMT-DS-20260623-KLINE-SYNC-2

关联事项：全局行情数据同步