AgenticSystemCore

Agentic System Core

用于发布可由机器发现的知识包的规范——Agentic Knowledge Web。

此仓库包含规范本身——编号的规范性规则、三个 JSON Schema、一个 OWL 2 RL 本体和一套一致性测试向量——以及实现该规范的参考引擎、其命令行工具 agsc，还有 AGSC-09-90 的九个独立检查器——七个验证器和两个生成器——任何人都可以用它们检查任何该格式的发行版（仓库还包含维护者自己的工具，这些工具不会随发行版发布）。

状态

已发布。 此代码树对应规范 1.0.0。spec/00-overview.md 是权威文件，应阅读该文件，而不是此处的说明。各软件包——npm 上的 agentic-system-core 及其短别名 agsc-cli，以及 PyPI 上的 agentic-system-core——版本号为 1.0.1（见下方“版本”），并从软件包标签发布；此前用于预留名称的占位包不包含任何运行时代码，在 npm 上已标记为弃用，在 PyPI 上已撤回。使用 npm install agentic-system-core 或 pip install agentic-system-core 安装。参考引擎声明符合 Level 3（其声明）。

版本。 两个版本号，分别说明。规范版本（spec_version，在 spec/00-overview.md 中声明）为规则、Schema、词汇表和一致性测试向量命名；Bundle 在 agsc.config.json 中声明该版本。软件包版本（npm 上的 package.json、agentic-system-core 和 agsc-cli，以及 PyPI 上的 agentic-system-core）为实现命名；对于不更改任何规则和任何输出字节的补丁——例如依赖项修复或检查缺陷修复——只更新此版本。仅软件包更新的发行版带有软件包标签 v<version>，不带规范标签。agsc --version 会打印软件包版本；一致性声明会同时列出两个版本（“agentic-system-core 1.0.1 conforms to AgenticSystemCore 1.0.0, Level 3”）；变更日志会说明每次发行是否更新了规范。

规范的官方网站是 AgenticSystemCore.com。

三句话介绍

Bundle 是一个包含多个 Markdown 文件的文件夹，每个文件顶部都有一小段类型化字段；规范规定如何将该文件夹转换为一个知识节点——静态网站、图谱、搜索索引、供 Agent 使用的文本文件以及发现文档——并确保不同实现生成相同的字节内容。人和 Agent 通过普通网址读取节点，只能通过由人确认的提案来更改节点，并将节点中的条目组合成一个起始框架——供架构师或 Agent 运行时启动时使用的文件。节点之间无需服务器中转即可相互发现和引用。

有何不同

据作者所知，没有其他系统能将以下特性结合起来：通过已注册的 Web 机制进行发现；发现文档中的每个制品链接都带有完整性摘要；采用已发布本体的类型化图；其机器制品的字节内容由预期字节符合性向量固定；治理机制要求每项变更——无论来自人还是 Agent——都以附带溯源信息的提案形式提交，并由人员批准（直接批准，或依据人员记录在节点配置中的常设规则批准）；还能将相同文件组合成启动用框架，而且整个过程无需任何服务器。

这是对规范文本及其向量的主张，并非性能主张。其他系统也具备其中一些特性；带日期的比较见 docs/RELATED-WORK.md。

特性	含义	说明和验证位置
通过已注册机制发现	在一个众所周知的地址提供一组链接，并通过已注册的关系 describedby 找到	AGSC-06-07、AGSC-06-25；tools/validate-wellknown
每个制品链接都带有摘要	在 Level 2 中，发现文档中指向节点所构建文件（图文件、llms.txt、NOW、技能和面板索引、账本、本体文件）的每个链接都带有该文件的 SHA-256；指向界面、许可证页面、对等节点和贡献目标的链接则不带摘要	AGSC-06-08；discovery 向量
采用本体的类型化图	十四种类型化链接、四种 RDF 视图，以及已发布的 OWL 2 RL 本体	spec/05-graph.md、ontology/agsc.ttl
由向量固定字节内容	两种实现使用同一个 Bundle 时，会生成相同的机器文件	AGSC-04-24；tests/vectors/
带溯源信息的治理	每项变更都是附带溯源信息的提案；由人员批准；账本根据历史记录生成	spec/08-governance.md（AGSC-08-08、AGSC-08-20）
组合成启动框架	所选条目会沿其链接闭包扩展，生成七种文件，供架构师或 Agent 运行时用作启动基础	AGSC-07-12；agsc compose
无服务器	这是文件格式和静态文件；未定义协议、服务器、数据库或推理器	AGSC-00-02

除了这种组合外，还有一些特性各自也能在其他地方找到：六种使用模式 （docs/plain/modes.md）；每个条目页面和 /compose/ 上都提供 七种工具，供浏览器自带的 Agent 使用，且与本地工具服务器完全一致（AGSC-09-16）； 八种插件类型，并承诺向前兼容（docs/PLUGINS.md， AGSC-00-24）；每个界面上都标注了内容版本 （AGSC-04-25）；以及由客户端遍历的联邦，而非由节点遍历（AGSC-11-06）。

最适用的场景

面向 Agent

• 供单个 Agent 使用的记忆。 Bundle 中的 agsc mcp 为助手提供七种工具，可按地址搜索、读取、追踪链接并引用条目；没有任何数据会离开本机 (Mode 1, use case L1)。
• 供多个 Agent 共享的记忆。 每个 Agent 都读取同一批已发布文件，只有经过人工批准的提案才能写入 (Mode 1, docs/CONNECTORS.md)。
• 技能来源。 每个集群都会成为一个技能包，其中包含其已发布条目——Agent 遵循的部分是其中的操作流程——并附带记录这些内容摘要值的锁定文件，可安装到 Agent 工具文件夹中；来自其他仓库的技能则作为操作流程引入 (Mode 3, use case L4)。
• 起始脚手架。 选定的条目会构成一个脚手架——包含七类文件，架构师或运行时可据此开始；它不是一个正在运行的系统，且 1.0 版本不提供针对特定运行时的渲染 (Mode 4, use case M5)。
• 供 Agent 团队使用的实时看板。 Agent 在共享看板上认领并完成任务，直至任务全部完成；决策权仍由人掌握 (Mode 5, use case M1)。
• 跨节点知识。 客户端读取多个节点的图谱转储，并在本地合并，每条外部结果都会标明其来源；在 1.0 版本中，遍历功能是引擎的库函数，而非命令 (Mode 1, use case D4)。

面向个人

• 一个能够自我纠正的 wiki。 输入 Markdown，输出经过检查并带有链接的网站；每项更改都会经过审核（模式 0、用例 L5）。
• 项目的动态规范。 将决策、规范、任务和关卡纳入统一治理的记忆，并通过引导文件让编码 Agent 保持正确方向（模式 2、用例 L3）。
• 模式库。 概念附有来源和溯源信息，无需 JavaScript 即可阅读，还能组合成起步架构（模式 4、docs/USE-CASES.md）。
• 团队看板。 将来自 GitHub、GitLab、Jira、Trello、Linear、Asana、Notion、Obsidian 或纯 Markdown 的看板转为实时看板，也可以再转回去（模式 5、用例 M7）。

快速开始

从克隆此仓库开始（Node 22.13 或更高版本）：

npm ci                                   # the exact pinned libraries
npm test                                 # the whole suite, offline
REPO=$PWD; cp -r tests/fixtures/minimal /tmp/agsc-try && cd /tmp/agsc-try
SOURCE_DATE_EPOCH=1767225600 node "$REPO/bin/agsc.js" ci   # lint, build twice, compare, verify: "ci: pass"

处理你自己的 Markdown 笔记文件夹（Node 22.13 或更高版本、git、POSIX shell）：

npm install agentic-system-core                          # in a working folder
export PATH="$PWD/node_modules/.bin:$PATH"               # puts agsc on the PATH
cd my-notes && agsc init                                 # each note gets a header and moves to content/concepts/
mkdir -p .well-known && printf 'Contact: mailto:[email protected]\n' > .well-known/security.txt
git init -q && git add -A && git commit -q -m 'my notes' # the build takes its instant from this commit
agsc ci                                                  # ci: pass (warnings are advice, errors stop)
agsc build                                               # the site, the graph and the agent files in www/

如果没有安全联系人，ci 会以 AGSC-E901 停止；如果没有提交（或 SOURCE_DATE_EPOCH），则会以 AGSC-E204 停止。 模式 0 指南 会逐步讲解，并列出每条命令输出的内容；另外还有五份 指南 分别介绍其他模式。如需连接助手，请阅读 docs/USING-WITH-ASSISTANTS.md。 如需让编码 Agent 熟悉引擎本身，请安装位于 skills/agentic-system-core/ 的 Agent 技能：npx skills add andreibesleaga/agentic-system-core， 或者在 Claude Code 中运行 claude plugin marketplace add andreibesleaga/agentic-system-core （市场配置文件 .claude-plugin/marketplace.json 指向 plugins/ 中的插件）。

适用对象、可获得的内容及试用方式

读者	目前能获得什么	试用方式
拥有一文件夹笔记的人	笔记静态站点，带搜索功能；每个页面也提供 Markdown 格式，以及供助手使用的图谱文件和文本文件；不需要模型或服务	上面的快速入门；模式 0 指南
开发者	本地工具服务器：助手可通过七种工具访问你的文件夹；没有任何内容会离开本机	agsc mcp，按 docs/USING-WITH-ASSISTANTS.md 中的说明进行设置；模式 1 指南
采用 Agent 辅助开发流程的团队	决策、规范、任务和关卡都作为经过检查的文件保存；一个 steering 文件，为每个编码助手提供相同的字节内容；一个关卡编译为一项必需的 CI 检查	模式 2 指南；agsc ci、agsc export --steer
将流程保留为技能的团队	每项流程都作为可安装的技能包，依据锁文件检查且不包含脚本；技能集合和规则文件夹作为流程导入，技能包再导出以供五种工具使用	模式 3 指南；agsc skills install .claude/skills；agsc import --from skills --list <clone>
架构师	一组依据类型化链接检查过的条目，并写入七类文件（Agent 指令、C4 模型、图表、arc42 框架、决策记录、技能文件）：这是一个起点，而非运行中的系统	模式 4 指南；agsc compose <slug>… --zip，或访问实时节点的 /compose/ 页面
在实时看板上协作的人与 Agent 团队	任务作为经过检查的文件保存，每个包含任务的集群都会发布为看板；认领和移动操作通过工具服务器以提案形式提交，由人员合并；看板文件可与十一种项目工具互相导入和导出	模式 5 指南；agsc import --from board --format jira <folder> --dry-run
实现或检查此格式的工程师	带预期字节内容的测试用例；可检查任意实现文件的检查器；另有一个 Python 检查器	agsc conform --level 3；node node_modules/agentic-system-core/tools/validate-wellknown https://agenticsystemcore.com/.well-known/knowledge-linkset --level 2；docs/IMPLEMENTERS-GUIDE.md
安全审查员	根据 git 历史重新推导并离线检查的账本；agsc-host verify-anchor 会依据构建结果检查的锚点文件；经 ci 检查的 security.txt；每个工具结果中都将不可信文本明确隔离；带有评分的安全语料库	agsc verify --ledger；docs/SECURITY-CONSIDERATIONS.md、SECURITY.md；安全审查员的场景
研究人员	可离线运行且无需模型或密钥的基准测试工具包；以 JSON-LD、Turtle 和 N-Quads 格式表示的图谱，这些格式包含相同的陈述；可引用的引用文件和符合性报告	docs/BENCHMARKS.md、docs/MEASUREMENTS.md、CITATION.cff；研究人员的场景
内容受访问控制保护的发布者	一个表明自身存在、但内容仍受访问控制保护的节点：发现文档保持公开，不包含公开节点所展示的捆绑信息，检查器也接受这些信息缺失的情况	在 agsc.config.json 中设置 "visibility": "restricted"（spec/11-boundary.md 中的 AGSC-11-20）；受限发布者的场景
正在决定是否依赖它的管理者	可依赖的内容（开放许可证、永久地址、已归档的版本、依据已发布字节内容进行检查）与不可依赖的内容（只有一位维护者、不承诺支持、没有计划安排）；每个外部步骤的状态；安全策略	阅读 GOVERNANCE.md、SECURITY.md 和状态页；查看实时节点：https://patterns.agenticsystemcore.com/
阅读节点的 Agent 或其运营者	一份列出每个机器文件及其摘要的发现文档；位于固定地址的文本文件、文本块和图谱文件	curl -s https://agenticsystemcore.com/.well-known/knowledge-linkset，然后运行上面的检查器命令

从哪里开始阅读

docs/START-HERE.md 会为每类读者——好奇的读者、有笔记的人、开发者、使用编码助手的团队、使用其他语言的实现者、架构师、经理、Agent、标准审查者或维护者——指引一条阅读路径。在此代码仓库中工作的 Agent 和编码助手应先阅读 AGENTS.md。

文档导航

官方代码仓库位于 https://github.com/andreibesleaga/agentic-system-core；网站位于 https://agenticsystemcore.com。

主题	阅读
规范（标准本身：343 个规则 ID，其中 332 个处于启用状态，共十二章）	spec/ — 从 spec/00-overview.md 开始；docs/plain/ 中提供了通俗易懂的版本
如何阅读规范	docs/SPEC-ORIENTATION.md，docs/SPEC.md
协议：发现文档、链接集、摘要、对等方、工具接口	docs/PROTOCOLS.md，spec/06-surfaces.md，spec/11-boundary.md
Internet-Draft（众所周知的链接集；一份个人 Internet-Draft）	internet-draft/
架构和词汇（JSON Schema、OWL 2 RL 本体、JSON-LD 上下文）	schema/，ontology/
架构	docs/ARCHITECTURE-GUIDE.md，docs/ARCHITECTURE-DDD.md，docs/diagrams/
所依托的标准及相关工作	docs/RELATED-WORK.md，docs/COMPLIANCE-CROSSWALK.md
一致性：级别、向量、如何陈述声明	spec/09-conformance.md，spec/10-implementation-profiles.md，tests/vectors/，docs/CONFORMANCE-STATEMENTS.md
使用其他语言实现	docs/IMPLEMENTERS-GUIDE.md
使用方法：模式、指南、演示、连接器、助手	docs/plain/modes.md，docs/guides/，docs/DEMOS.md，docs/CONNECTORS.md，docs/USING-WITH-ASSISTANTS.md
插件和扩展点	docs/PLUGINS.md
安全和威胁模型	docs/SECURITY-CONSIDERATIONS.md，SECURITY.md
工程、测试、测量	docs/ENGINEERING.md，docs/TESTING.md，docs/MEASUREMENTS.md，docs/BENCHMARKS.md
需求和用例	docs/PRD.md，docs/USE-CASES.md，docs/REQUIREMENTS-MATRIX.md
后续计划	docs/ROADMAP.md
治理、商标、贡献、许可	GOVERNANCE.md，TRADEMARK-POLICY.md，CONTRIBUTING.md，NOTICE
术语表和完整文档索引	docs/GLOSSARY.md，docs/README.md

参考引擎

规范的参考实现位于此仓库的 src/ 目录下。它声明符合 Level 3，即完整引擎。只有在该 Level 的向量集测试全部通过后，才会声明符合任意 Level，并按 AGSC-09-01（AGSC-10-05）规定的形式发布；引擎的声明记录在 docs/CONFORMANCE-STATEMENTS.md 中，其中说明了声明各部分的依据，内容如下：

agentic-system-core 1.0.1 符合 AgenticSystemCore 1.0.0，Level 3。 已于 2026-10-12 根据已发布的一致性向量完成验证：在 20 个有用例的领域（adopt、boards、boundary、build、bundle、 chunks、cli、compose、conform、discovery、export、frontmatter、graph、import、 jcs、ledger、links、lint、prov、slug）中，243 个用例全部通过，其中 242 个必需用例、1 个可选用例；排除 7 个已撤回用例；使用 Unicode 17.0。部署配置文件： cloudflare-pages——参考配置文件：agsc build 写入的 _headers 和 _redirects。表面：llms-txt（由 disc-0013、disc-0014 证明）、 chunks（由 chk-0001、chk-0002、chk-0003、chk-0004、chk-0005、chk-0006、 chk-0008 证明）、webmcp（由 cli-0003 证明）。

AGSC-09-07 中的全部 16 个动词均已实现；按照 AGSC-09-94 的要求，run 和 trace 默认关闭。agsc init 会接管一个 Markdown 文件夹；首次构建前，发布者需添加带有 Contact: 行的 .well-known/security.txt（RFC 9116），并提交一次，或设置 SOURCE_DATE_EPOCH，正如 init 结束时的提示所述；agsc ci 执行检查，agsc build 则构建站点。

• src/README.md 是引擎自身的文档，介绍有界上下文、模块映射、动词 → 模块表、如何运行一致性向量，以及本项目发现并报告而非绕过的规范条目列表。
• tests/vectors/** 是验收测试，也是以其他语言实现此格式时真正重要的部分：移植版本需要 spec/、schema/、ontology/ 和这些向量，而不需要 src/ 中的任何内容。
• npm test 会运行整个测试套件，一致性测试运行器会输出一行摘要。
• docs/PLUGINS.md 是插件契约：此格式允许的 8 种类型（AGSC-00-24）、每种类型的插件可以读取和输出什么、绝不能做什么、引擎如何发现插件，以及在 1.x 系列中承诺不会破坏什么。examples/plugins/ 为每种类型提供了一个最简示例；在 1.0 版中，命令会加载其中 3 种类型（内存适配器、组合输出器和部署配置文件），另外 5 个示例仅由插件契约测试验证。

引擎的组织方式只是实现选择之一，不属于格式的一部分。如果本引擎与规范存在冲突，以规范为准。

软件包承诺在 1.x 系列中保持稳定的内容。 命令行——命令 agsc、agsc-host 和 agentic-system-core，它们的动词、标志、退出代码和输出封装（AGSC-09-07 至 AGSC-09-12）——docs/PLUGINS.md 中的插件契约（插件 API 1.0.0）、作为程序运行的 9 个检查器（node tools/<name>），以及 require('agentic-system-core') 返回的 6 个名称：LINK_RELATION、PROFILE_URI、WELLKNOWN_SUFFIX、run、specVersion 和 version。package.json 未声明 exports 映射，因此仍可对 src/、bin/ 和 tools/ 下的所有文件调用 require；这些文件均不在承诺范围内，其名称和签名可能在任何版本中变更。唯一例外是 bin/agsc.js 的 run()，它是 agsc-cli 别名软件包调用的入口。

从候选版本升级。 CHANGELOG.md 为每次升级步骤设有一个章节：从 1.0.0-rc.7 升级，位于 1.0.0 下；以及从 1.0.0-rc.6 升级，位于 1.0.0-rc.7 下。每个章节都会说明：使用早期版本构建的节点现在可能会遇到哪些拒绝情况、构建文件有哪些变化，以及应如何处理。仍在使用 1.0.0-rc.6 的节点应先阅读第二个章节，再阅读第一个。

连接 Agent 和代码仓库

docs/CONNECTORS.md 按路由说明了 Agent 或框架如何使用已发布的 Bundle——包括引导文件、技能包、MCP 服务，以及 COGX 记忆归档（agsc export --to cogx / agsc import --from cogx）。COGX 是 Cognee 读取和写入的格式；迁移到 Cognee 时，它会将 Mem0、LangMem、Letta 和 Zep 的记忆转换为该格式。examples/connectors/ 中包含可运行的示例，docs/USE-CASES.md 则通过命令演示了二十一个具体场景。

每次推送时检查 Bundle（GitHub Actions）。 本仓库根目录的 action.yml 是一个复合操作，会使用与该操作处于同一提交的引擎运行 agsc ci，因此你填写的 ref 会固定引擎版本。请将它固定到软件包标签 v1.0.1（不要使用规范标签：软件包可以打补丁，而规范仍保持 1.0.0），或固定到该标签的完整提交 SHA；仅授予任务读取权限，并获取账本读取所需的历史记录：

permissions:
  contents: read
jobs:
  agsc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<commit-sha>
        with:
          fetch-depth: 0
      - uses: andreibesleaga/[email protected]

每次提交前运行 lint（pre-commit）。 .pre-commit-hooks.yaml 提供一个名为 agsc-lint 的钩子，只要条目或配置有更改，就会对整个 Bundle 运行 agsc lint。以相同方式将 rev 固定到软件包标签或其完整提交 SHA。该钩子使用系统 Node 运行，系统 Node 必须为 Node 22.13 或更高版本；如果系统 Node 版本较旧，请为该钩子设置较新版本的 language_version：

repos:
  - repo: https://github.com/andreibesleaga/agentic-system-core
    rev: v1.0.1
    hooks:
      - id: agsc-lint

本项目的制作方式

本项目由 Andrei N. Besleaga 在 AI 助手的协助下编写并维护。由人决定编写内容，助手负责起草和检查，再由人阅读、编辑并批准所有发布内容，并对此负责。每个已发布条目都会记录其文本的创作方式，并注明负责的人员。由 AI 协助编写，由人审核并发布。 协助范围包括文本、代码、图表和示意图。引擎本身不会调用任何 AI 模型，也不包含模型适配器。规范所述的模型步骤均为可选步骤：实时运行由引擎外部的 Agent 执行——例如 Claude Code 或脚本——作为 agsc mcp 或页面工具的客户端，并遵守所在通道声明的限制（AGSC-08-28）；运行该 Agent 的人员对此负责。助手或 Agent 根据本项目编写的内容属于其自身输出，并非作者的声明。

本项目不作何种声明

这是一个人的独立作品，以现状发布，不提供任何形式的保证，也不对使用本作品导致的任何后果承担责任。其中任何内容均不构成法律或专业建议。本仓库中提到的任何标准组织、基金会、公司或机构均未审查或批准本作品，也与本作品无关；本作品并非 IETF、W3C 或任何其他组织的文件。其他产品和组织名称均为其所有者的商标，仅用于说明所指对象。 对于许可未明确授予的所有权利，均予以保留；本项目也不保证作品或其地址会一直可用。

声明

AgenticSystemCore™ 是 Andrei N. Besleaga 的商标。其他名称均归其所有者所有。

许可证

内容	许可证
引擎、命令行和检查器	Apache-2.0（LICENSE）
JSON Schema、本体、标识符和发现文档	CC0-1.0
skills/ 和 plugins/ 下的 Agent 技能，以及 .claude-plugin/ 下的插件市场文件	CC0-1.0
spec/ 下的规范文本	Apache-2.0
tests/vectors/ 下的一致性测试向量	Apache-2.0
docs/ 下的文档、features/ 下的场景和 examples/ 下的示例	Apache-2.0
w3c/ 下的 W3C 格式个人草案	CC-BY-4.0
internet-draft/ 下的 Internet-Draft	Apache-2.0；作为已发布的 Internet-Draft，也受 BCP 78 和 IETF Trust 法律条款约束
已发布节点的文字内容——条目正文、描述以及承载这些内容的页面和导出文件	LICENSE-CONTENT 中的内容使用条款

外部贡献须按 CONTRIBUTOR-AGREEMENT 中的协议签署贡献者声明；该协议的代号为 CA-v1；CONTRIBUTING.md 用通俗语言说明了这意味着什么。GOVERNANCE.md 说明由谁作出决定，以及维护者停止维护时会如何处理；TRADEMARK-POLICY.md 说明如何使用项目名称；docs/CONFORMANCE-STATEMENTS.md 说明如何声明某个实现符合规范；CODE_OF_CONDUCT.md 说明对参与者行为的期望；SECURITY.md 说明如何私下报告漏洞。

© 2026 Andrei N. Besleaga。代码：Apache-2.0。Schema、本体、标识符和发现文档：CC0-1.0。文字内容：LICENSE-CONTENT 中的内容使用条款。