企业官网建设流程全解析

AAS Core 实战指南：为 Codex 与 Claude Code 构建本地、Agent 自选的技能栈控制平面

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills

AAS Core 是 agentic-awesome-skills 项目中面向 Codex 与 Claude Code 的本地、只读、优先 Agent 选择的控制平面：它让编码代理在已验证的本地 catalog 中搜索并阅读全部技能，自行决定精确的 skill ID，并把选择固化到可复现的aas-stack.json期望状态中，最终通过 CLI 生成不可变的预览计划。读完本文，你将掌握从 MCP 配置、Agent 选栈契约、manifest 校验到计划预览与证据导出的完整实战链路，并理解"Agent 检查与选择、AAS 记录与验证、你来掌控"这一职责划分原则。

AAS Core 的定位与职责边界

AAS Core 是 Agentic Awesome Skills 的本地"控制平面"（control plane）。其核心职责是：让 Codex 或 Claude Code 搜索并读取已验证的本地 catalog，由代理精确选择 skill ID，再把这一选择保存在aas-stack.json中，供用户在任何目标发生变更之前预览确认。

关键边界在于：Core 不对技能进行排名，也不推荐技能。从源码结构看，这一设计贯穿始终——MCP 服务器实现中注册的全部工具都带有readOnlyHint: true，而search_skills的官方描述明确声明返回结果"无相关性分数、无排名、无推荐、无本地状态变更"（见 server.js 的TOOL_DEFINITIONS）。

发布边界：npm 包 14.6.0 在 AAS Core 之前发布，无法用于引导 Core。支持 Core 的包从 15.x 系列开始；务必使用 release notes 明确声明包含 AAS Core 的精确版本，不要使用未经审查的浮动 tag。

完整使用流程

依据关联文档的流程骨架，结合英文主文档 docs/users/aas-core.md 中的详细步骤，完整链路如下：

1. 使用官方 AAS CLI 为 Codex 或 Claude Code 配置本地 MCP stdio（先执行预览命令获得批准摘要，再以--approve确认）；
2. 允许 Agent 调用search_skills与get_skill，让其按语义自行评估结果，再以profile与选定的 ID 调用compose_stack；需要时用inspect_stack验证、用diff_stack比较；
3. 审查 schema 2 的aas-stack.json——其中包含profile与 Agent 按正确顺序选择的 ID；
4. 用 AAS CLI 校验 manifest 并预览精确计划；
5. 看到计划后停下来；除非主动参与受控预览开发，否则不要继续后续阶段。

英文文档给出的端到端流程（docs/users/aas-core.md）可概括为：项目 → Codex/Claude 检查仓库 → Agent 搜索并读取完整本地 catalog → Agent 选择精确 skill ID →compose_stack在内存中验证并返回 manifest → 客户端或 CLI 持久化aas-stack.json（可选附带证据 sidecar）→ 你审查产物 →aas stack validate→aas stack plan（仅预览，不改动技能）→aas stack audit（可选跨产物一致性检查）。

信任边界

关联文档明确列出了四条信任边界，展开如下：

• AAS MCP 本地运行且只读：MCP 不会安装、删除、应用或更新任何内容。它不扫描仓库，也不决定哪些技能最好；语义决策完全交给 Codex 或 Claude Code 自身的项目理解与判断。
• 搜索结果完整、分页、有序：返回结果使用稳定的 catalog 顺序，不含分数或排名。每个 catalog 技能都保持可单独搜索、可读取、可被 Agent 选择；缺失或不完整的元数据不会使技能失去候选资格。
• validate与plan是被认可的预览流程：apply和recover默认关闭，尚未成为经过认证的安全承诺。
• 目录身份与运行时在本地验证：默认情况下，项目数据不会发送到 AAS 服务。

源码层面的印证同样明确：tools/scripts/tests/aas_core_public_docs_contract.test.js专门断言公开文档中"128 个技能的技术上限"、"原始search_skills查询"等契约表述与实现一致。结构与身份合法性不等于语义契合、配置正确性、运行安全或可安全应用——这是 Core 反复强调的 [IMPORTANT] 边界。

配置本地 MCP（含原生 Windows）

精确版本配置命令

npm exec --yes --ignore-scripts --package=agentic-awesome-skills@17.4.0 -- aas mcp configure \ --host codex \ --scope user \ --config /absolute/path/to/codex/config.toml \ --cache-root /absolute/path/to/aas-cache

• 使用--host claude并传入对应的 Claude MCP 绝对配置路径即可配置 Claude。
• 第一条命令是预览：返回一个批准摘要（approval digest），不会改动宿主配置。审阅摘要后，用完全相同的方式重复命令并追加：

--approve <approval-digest>

配置是显式且完整性绑定的：AAS 安装或复用精确的、按内容寻址（content-addressed）的运行时，验证它，并且只改动自己托管的 MCP 配置段。若宿主未自动重载 MCP 配置，请重启宿主。

原生 Windows 与 Codex

• 原生 Windows 10/11 + Node.js 22 是 Codex 用户级适配器的受支持预览目标，支持 Codex CLI0.144.x配置形态。
• --config、--cache-root，以及替换既有配置时的--backup-dir，都必须使用 Windows 绝对路径。
• 预览阶段 AAS 用 PowerShellGet-Acl检查配置父目录（通常是%USERPROFILE%\.codex）与既有config.toml的属主；此阶段不检查缓存 DACL，也不调用icacls。
• 出现AAS_ADAPTER_WINDOWS_ACL_FAILED时，报告会给出被检查的path、ACLphase、退出status与受限的诊断信息；未解析的继承 ACE 名被当作不可信的 ACL 数据而非崩溃。预览失败时请检查报告的命名配置路径（而非缓存），并且在预览返回approvalRequired与approvalDigest之前不要加--approve。

MCP 工具集：九个只读工具

本地 MCP 通过 stdio 暴露以下只读工具，与 server.js 的 TOOL_NAMES 完全一致：

契约注入：能力覆盖契约通过 MCPinitialize的 instructions 注入，并在工具描述中强化（见 server.js 的AGENT_SELECTION_CONTRACT与 server.js 的initialize实现）。这是Agent 的义务，而非 Core 的排名或资格策略：Core 仍接受并保留任何结构合法的 catalog ID 集合，绝不为 Agent 做选择。

传输与限制：

• stdio 传输将每条完整 JSON 行（含换行）限制在256 KiB；普通请求与无关元数据保持 4 KiB 基础限制。compose_stack、inspect_stack、diff_stack与两个证据工具的参数可使用更大的帧（manifest 与台账常超过 4 KiB），但 schema 限制仍然生效。过大的 sidecar 请改用紧凑 JSON 传输与 CLI 检查器。
• stdio 队列最多接受32 个待处理帧，超限调用收到AAS_MCP_QUEUE_FULL及受限解析的请求 ID，客户端可据此重试；通知（notification）无应答，不能用于需要确认结果的操作。
• MCP 调用不会安装/删除技能、更新 catalog、编辑宿主配置、持久化栈或应用它。完整技能文本仅在请求时返回，且始终标记为不可信内容。

让 Agent 选择技能栈

方式一：从 catalog 候选清单（shortlist）起步

在 catalog 或 Workbench 中使用Explore skills by outcome描述任务或选择起始示例。浏览器从公共 catalog 中建议候选并解释哪些词条命中：名称与标签权重大于描述，专有词权重大于通用词——这是描述性相关性，不是质量分数、语义评估或效果基准。选择任何技能前务必检查完整说明与约束。

• 使用without Supabase或senza Supabase做显式单术语排除；追加更多术语可重复该短语，解析出的排除项会被展示。其余自然语言约束仍需 Agent 复核。
• 每个候选都暴露来源（provenance）、许可证、声明的风险与安装信息（含缺失字段）——这些是作者提供的元数据，不是可靠性徽章。
• Workbench 仅在打开 discovery 后才下载公共 catalog；产物审查不需要该下载，也绝不会上传导入的产物或目标。目标仅存于页面内存，只有显式加入 shortlist 的 ID 使用浏览器本地清单。无用量测量、无安装日志、无集中收集。
• 短清单 ID 存储在浏览器本地存储中。Agent 返回 manifest 并经你审查后：持久化并校验 manifest → 生成不可变 CLI 计划 → 显式将这两个产物导入 Workbench。

方式二：直接在编码 Agent 中启动

给 Agent 目标结果与约束，把选择判断权留给 Agent（完整提示词见 docs/users/aas-core.md），核心要点如下：

Inspect this repository. Search and read the complete local AAS catalog, then enumerate the project's primary capability areas. For each capability, run a focused search, paginate or refine until you find plausible candidates, and use get_skill to compare multiple candidates when available. Select at least one non-redundant valid skill for every covered capability. Explicitly report as a catalog gap any capability for which the catalog has no valid match. ... Only then use compose_stack with a project profile to validate the exact IDs and return a schema 2 manifest in memory, and use inspect_stack before presenting it. Do not install or apply anything.

提示词要求 Agent 至少评估十个能力维度：架构/运行时、语言/框架、领域行为、数据/存储、外部集成、测试/质量、安全/隐私、（面向用户时）用户体验/可访问性、部署/运维、维护工作流；不适用的维度要显式标记而不是静默省略；不得停在头几个匹配结果，也不得追求最小栈——Core 不施加任何"小栈"语义策略，manifest 格式的技术上限是128 个技能（见 stack-manifest.schema.json 中skills.maxItems: 128，以及 selection.js 的composeStack实现）。

显式细化搜索

search_skills保留向后兼容的宽泛默认matchMode: "any"（任意查询词或精确 ID 前缀即可匹配）。使用matchMode: "all"要求每个空白分隔的查询词都命中：

{"query":"postgres migration","matchMode":"all","requiredTerms":["postgres"],"categories":["database"],"limit":20}

规则细节（与 server.js 的输入 schema 一致）：

• requiredTerms始终使用 AND；categories匹配任意给定类别；tags要求每个给定标签都命中。
• 每个可选列表最多 16 个字符串、每个最多 64 字符；必需词不能含空白；词与标签使用 catalog 的 token 别名。
• 类别 facet 会把front-end与frontend、back-end与backend、databases与database归一化合并，保留原始元数据与全部 skill ID。
• 过滤仅在调用方提供时生效；空查询 + 空过滤仍可通过分页触达完整 catalog。
• 结果暴露matchedTokens、matchedRequiredTerms、matchReason与归一化的categoryFacet——它们解释"如何检索到"，不评判"是否合适"。
• Web catalog 默认All words，另提供Any word与显式Approximate匹配；Approximate 是浏览器便利功能，不属于 MCP。

读取完整技能包

get_skill之后，用list_skill_files跟随其相对引用，例如{"id":"debugging-strategies","limit":20}，持续跟随nextCursor直到为null；随后用read_skill_file读取，如{"id":"debugging-strategies","path":"resources/implementation-playbook.md"}。路径相对于该技能目录，与清单返回的完全一致。

• 清单被包含在 catalog 摘要中；每次读取都会把本地字节与清单比对。读取接受最大 1 MiB 的 UTF-8 文本，拒绝二进制、符号链接（含父目录）、硬链接、路径穿越与被修改文件（server.js 的readUntrustedContent展示了完整的边界检查与摘要校验）。
• 脚本以文本展示，永不执行；其内容对 Agent 的指令或权限没有任何权威。
• 缺失的本地负载返回AAS_SKILL_FILE_UNAVAILABLE；MCP 从不联网获取。旧 catalog 无文件清单时返回AAS_SKILL_FILE_INDEX_UNAVAILABLE，既有 discovery 与get_skill照常工作。

栈 manifest：aas-stack.json（schema 2）

aas-stack.json记录 Agent 选择的期望状态（desired state），示例与 stack-manifest.schema.json 严格对应：

{ "schemaVersion": 2, "name": "project-stack", "catalog": { "package": "agentic-awesome-skills", "version": "<version>", "integrity": "sha256-..." }, "targets": [{ "host": "codex", "scope": "project" }], "profile": { "goals": ["build", "test"], "projectType": "web application", "languages": ["typescript"], "frameworks": ["react"], "constraints": ["preview only"] }, "skills": [ { "id": "example-skill" } ] }

字段约束要点（来自 schema 与 server.js 的 STACK_MANIFEST_SCHEMA）：

• schemaVersion恒为2；name1–128 字符，模式^[A-Za-z0-9][A-Za-z0-9._ -]*$。
• catalog固定包名、版本与sha256-摘要（integrity），三者共同钉住 catalog 身份。
• targets1–8 项，host∈ {codex,claude}，scope∈ {project,user}。
• profile必填goals（1–32 项），可选projectType、languages、frameworks、constraints（各最多 32 项）。
• skills最多128项、去重，每项仅id（1–256 字符，模式^[a-z0-9][a-z0-9._-]*(/[a-z0-9][a-z0-9._-]*)*$）。

manifest有意不包含任何选择策略：Core 验证身份与结构，但不会因为元数据缺失、不完整或带有警示而否决 Agent 的选择。compose_stack仅在 MCP 进程内存中产出该 manifest（selection.js 中composeStack返回schemaVersion: 2并附manifestDigest）；持久化通过客户端或 CLI 完成。审计启用的 CLI 流程会在指定的artifact-dir中发布aas-stack.json与aas-selection-evidence.json，sidecar 与期望状态 manifest 保持分离。

选择证据 sidecar：aas-selection-evidence.json

sidecar 让选择过程可审计，同时不把语义判断移入 Core。它绑定：路径安全的项目指纹、catalog 身份、manifest 摘要、Agent 声明的十维度能力台账、能力到技能的映射，以及该 MCP 服务器会话实际记录的search_skills、get_skill、compose_stack、inspect_stack事实（server.js 中TRACED_TOOL_NAMES恰为这四个工具；轨迹上限 512 次调用，见MAX_TRACE_CALLS）。

• export_selection_evidence接收台账，但轨迹取自服务器持有的会话状态，调用方无法注入或替换历史轨迹——这是非伪造保证的核心。
• 轨迹记录有效查询/游标/限制、显式提供的匹配模式与过滤、返回的 ID、打开的技能 ID、精确 compose ID、inspect 结果、安全错误码、确定性重试次数及规范输入/输出字节数；单调耗时单独记录在证据摘要之外。客户端名称与版本取自 MCP initialize（有效时）。
• sidecar 结构校验见 selection-evidence.schema.json。注意：搜索查询被逐字记录为事实轨迹数据，因此不要把密钥、凭据、私有源码文本或个人信息放进search_skills查询。
• 摘要使后续篡改可检测，但不是签名，也不构成跨会话身份证明。
• 发布 manifest 与导出的 sidecar 而不暴露单文件中间态：

aas stack create \ --selection /absolute/path/to/agent-selection.json \ --evidence /absolute/path/to/exported-evidence.json \ --artifact-dir /absolute/path/to/new-audit-artifact \ --require-evidence

目标目录必须尚不存在。CLI 校验两个产物，以aas-stack.json与aas-selection-evidence.json命名写入私有暂存文件，同步后以一次 rename 发布完整目录。原有stack create --selection ... --out ...的纯 manifest 路径仍受支持。

校验与预览计划：validate / plan / audit

自动化中务必使用绝对路径，并审阅每条命令的 JSON 结果：

aas stack validate --manifest /absolute/path/to/aas-stack.json aas stack plan \ --manifest /absolute/path/to/aas-stack.json \ --target codex:project \ --target-root /absolute/path/to/project \ --cache-root /absolute/path/to/aas-cache \ --runtime-integrity '<npm-sri>' \ --out /absolute/path/to/plan.json aas stack audit \ --manifest /absolute/path/to/aas-stack.json \ --evidence /absolute/path/to/aas-selection-evidence.json \ --plan /absolute/path/to/plan.json

• stack validate只读；stack plan只写请求的计划产物，不在目标中物化技能或 AAS 托管状态。不可变计划绑定 manifest、运行时、catalog、目标身份、当前托管状态与精确逻辑操作（计划结构见 plan.schema.json）。
• 使用已有目标目录。在main上，缺失路径、错误的文件/目录类型与拒绝访问会返回受限的AAS_CLI_*文件系统错误（16.8.0 起；原生异常消息与私有路径不会进入结果）。
• 从 16.8.0 起，仅当被校验的 manifest 只有一个目标时才推断--target，否则需显式给出如--target codex:project。运行时版本取自 manifest，其已验证 catalog 必须与 manifest 的 catalog 匹配。
• stack audit同样只读：独立校验三个产物，解析 manifest 钉住的已验证 catalog，报告 manifest 摘要、catalog 身份、目标与选定技能 ID 是否一致；结构非法或不可验证的产物失败关闭，合法但绑定不同的产物返回status: "inconsistent"与稳定原因码。
• 看完计划就停，除非你刻意参与受控预览开发。stack apply与stack recover仍是实验性命令，需要显式 opt-in。

使用已审查的选择：安装预览与直接安装

在main上，可从 Agent 的 manifest 直接生成安装预览，无需手动复制 ID：

aas stack install-preview \ --manifest /absolute/path/to/aas-stack.json \ --destination /absolute/path/to/project/.agents/skills

• PowerShell 下追加--shell powershell；--destination是实际技能目录，不是项目根。
• 命令校验 manifest 与其验证过的本地 catalog（可用--cache-root指定其他缓存），返回 shell 引号化的命令与可执行/参数字段。它不读取项目源码、不选技能、不执行任何内容，总是以--dry-run准备。
• 空选择与未知 ID 失败；目标使用与安装器相同的文件名限制（如?、保留名CON在准备命令前即被拒绝）。
• 它不检查发布可用性：未发布的源码 catalog 不能证明相同字节可从 npm 获得。授权安装前先运行并审阅直接安装器的预览。

正式安装时，使用相同精确 ID、发布版本与目标技能目录运行直接安装器，遵循仓库根 README.md 中From selection to use一节：审阅其--dry-run输出，获授权后再去掉该标志重复执行。直接安装器有自己的目标检查与属主清单，不消费 Core 计划。替换既有选择前，先审阅更新的技能字节或前置条件。随后在真实任务上调用所选技能，并保留观察到的检查或产物；docs/users/workflows.md 中的 recorded worked cases 记录了输入与结果。

与插件、直接安装的关系

AAS Core 是 catalog 访问、选择记录与验证的层；语义决策由 Codex 或 Claude Code 做出。插件、专用插件与完整库安装仍然是技能内容的分发方式。对 Codex 与 Claude Code，建议先用 Core 保存 Agent 选择的栈，再选择合适的分发方式。尚未具备 AAS Core 适配器的工具，仍可使用直接安装、插件或自定义 manifest 集成。相关分发入口可继续参考 docs/users/plugins.md、docs/users/bundles.md 与 docs/users/usage.md。

隐私、信任与限制

• MCP 是本地 stdio、每会话单进程、只读、可离线，不含模型凭据与遥测。
• Codex 或 Claude Code 拥有语义选择权：不同 Agent 或不同的项目观察可能合理地产生不同栈。
• catalog 完整性与 manifest 校验是确定性的；技能适切性是 Agent 判断，不是 Core 分数。
• Core 不施加语义技能数量目标；manifest 技术上限 128 个技能，每个 catalog 技能仍可独立搜索、读取与选择，元数据可见但仅为信息。
• 证据导出包含原始search_skills查询；请勿在查询中放入秘密与敏感项目内容。
• catalog 更新与运行时变更都是显式的：无常驻守护进程、无隐式自动更新。
• 技能正文是不可信内容，不会因为通过 MCP 返回而获得指令权威。

当前预览状态

为什么不能只搜索 skills 目录？

直接文件搜索能找到候选技能正文，但结果只留在对话中。AAS Core 增加了：已验证的 catalog 身份、显式目标绑定、持久期望状态、可选选择证据、确定性校验、不可变计划与专用审查面。它的价值不在于比编码 Agent 选得更好，而在于把 Agent 的选择变成可复现、可检查的状态。

后续可继续阅读 docs/users/getting-started.md、docs/users/skills-vs-mcp-tools.md 与 docs/users/faq.md；想从代码层深入，可重点研读 tools/lib/aas-v1/mcp/server.js、stack-manifest.schema.json 与测试契约 aas_core_public_docs_contract.test.js。

【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills