Skip to content

docs(agent-sec-core): add bilingual user guide and documentation guidelines#1311

Merged
casparant merged 1 commit into
alibaba:mainfrom
casparant:docs/user-guide-2
Jul 6, 2026
Merged

docs(agent-sec-core): add bilingual user guide and documentation guidelines#1311
casparant merged 1 commit into
alibaba:mainfrom
casparant:docs/user-guide-2

Conversation

@casparant

Copy link
Copy Markdown
Collaborator

Summary

Add comprehensive user documentation for AgentSecCore — the all-local, zero-Token security kernel for AI Agents.

Changes

New files

  • docs/user-guide/en/agent-security/agent-sec-core.md — English user guide
  • docs/user-guide/zh/agent-security/agent-sec-core.md — Chinese user guide

Modified files

  • src/agent-sec-core/AGENTS.md — Added "User-Facing Documentation Guidelines" section

Documentation Coverage

Module Covered
Prompt Scanner (4 modes)
Code Scanner
Skill Ledger (6-state lifecycle)
PII Checker
Security Baseline
Sandbox
Observability TUI
Security Events query
Agent framework integration (OpenClaw / Hermes / cosh)

Design Decisions (captured in AGENTS.md)

  • Lead with "all-local, zero Token cost" value proposition
  • Each capability module gets a dedicated section (no merging)
  • Default plugin behavior is observe-only (fail-open); blocking requires explicit opt-in
  • Code Scanner verdict set is strictly warn / pass — no invented risk levels
  • Skill Ledger full 6-state table must always appear
  • Installation priority: anolisa install → RPM → source build

Verification

  • CLI commands derived from actual code signatures
  • Bilingual consistency (en/zh structure mirrors)
  • Installation priority follows project convention (anolisa CLI → RPM → source)
  • AGENTS.md guidelines section follows content-boundary principle (framework-level guidance only, no duplicated CLI flags)

@github-actions github-actions Bot added component:sec-core src/agent-sec-core/ scope:documentation ./docs/|./*.md|./NOTICE labels Jul 3, 2026
@yangdao479 yangdao479 requested review from edonyzpc and yangdao479 July 3, 2026 09:44
@yangdao479

Copy link
Copy Markdown
Collaborator

sec-core user guide(zh/en)CLI 部分已基本正确。主要问题集中在 src/agent-sec-core/AGENTS.md 新增的 "User-Facing Documentation Guidelines" 节,有几处与源码/文档本身矛盾:

  1. 模型来源错误:AGENTS.md 写 "models come from GitHub Releases / HuggingFace",但源码使用 modelscope.snapshot_downloadprompt_scanner/models/model_manager.py:92),user guide 也正确写了 ModelScope。应改为 ModelScope。

  2. 章节顺序自相矛盾:AGENTS.md 规定 "CLI → cosh → OpenClaw → Hermes",但同 PR 的 user guide 实际写的是 OpenClaw → Hermes → cosh。二者需要统一。

  3. Code Scanner verdict 描述不准确:AGENTS.md 和 user guide 都写 "strictly warn/pass only",但 Verdict 枚举实际定义了 pass/warn/deny/error 四种(code_scanner/models.py:18-22),_compute_verdict 在规则 severity 为 deny 时会返回 Verdict.DENY。建议改为 "当前内置规则仅产生 warn/pass/error,但引擎支持 deny"。

  4. 模块计数对不上:AGENTS.md 说 "Six capability modules: ...Sandbox",但 user guide 无 Sandbox 独立章节,实际有 Observability + Events 两个额外章节(共 7 节)。

  5. config.toml 示例中 skill-ledger 的 enable_block 字段:代码未消费该字段(实际通过 policy 控制),写在示例中会误导用户。

@casparant casparant force-pushed the docs/user-guide-2 branch from 1253829 to dd3545b Compare July 3, 2026 10:51
…elines

Add comprehensive user documentation for AgentSecCore (en/zh) covering
all seven capability modules: Prompt Scanner, Code Scanner, Skill Ledger,
PII Checker, Security Baseline, Observability, and Security Events.

Also adds a Documentation Guidelines section to src/agent-sec-core/AGENTS.md
with an Authoring Protocol that mandates code-level verification before
writing any factual claim (enum values, model sources, config fields).

Assisted-by: Qoder:latest
Signed-off-by: Caspar Zhang <caspar@linux.alibaba.com>
@casparant casparant force-pushed the docs/user-guide-2 branch from dd3545b to ce0b5c1 Compare July 3, 2026 11:27
@yangdao479

Copy link
Copy Markdown
Collaborator

LGTM! THX

@casparant casparant merged commit c9d022d into alibaba:main Jul 6, 2026
18 checks passed
@casparant casparant deleted the docs/user-guide-2 branch July 6, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:sec-core src/agent-sec-core/ scope:documentation ./docs/|./*.md|./NOTICE

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants