feat(expert): unify workflows and DashScope attribution

.gitignore

@@ -8,8 +8,6 @@ build/
 *.spec
 !agenticx.spec
 .claude/
-.acli/
-.agenticcli/
 /.agenticx/
 /keys.log
 traces/

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-11-11
+
+### Added
+
+- End-to-end App Catalog installation and verification quick starts, including
+  the separate Expert activation step and one-shot `agenticx -c` usage.
+- DashScope and MaaS request attribution through
+  `x-dashscope-sdk-client` and `x-dashscope-sdk-session-id` across Native,
+  OpenAI-compatible, Anthropic-compatible, MCP, ASR, and TTS requests.
+  Third-party endpoints do not receive these headers.
+
+### Changed
+
+- Expert management now consistently uses `agenticx expert`, `/expert`,
+  `expert_repo`, and `expert_branch`; legacy Example command and configuration
+  names have been removed.
+- English and Chinese guides now cover the current CLI, interaction, Skill,
+  Session, and Server commands and clarify App installation versus Expert
+  activation.
+
 ## [1.0.0] - 2026-11-10
 
 ### Added
@@ -31,10 +51,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   and `user-guide_zh.md`.
 - Public guides and migration documentation live at the repository root.
   Source distributions exclude the internal `md/` directory.
-- Example downloads default to the public `dashscope/dashscope-agenticx-experts`
+- Expert downloads default to the public `dashscope/dashscope-agenticx-experts`
   repository on branch `main`; explicit repository overrides remain supported.
 - App Catalog downloads read only `apps/<name>/`, with no fallback to legacy
-  top-level example directories or an interactive repository setup prompt.
+  top-level Expert directories or an interactive repository setup prompt.
 
 ### Fixed
 
@@ -74,7 +94,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   do not match a known API-key pattern.
 - Credential assignments are redacted regardless of length, and complete or
   truncated multiline private-key blocks are removed from text payloads.
-- Example download and restore reject path traversal, symbolic links, and
+- Expert download and restore reject path traversal, symbolic links, and
   attempts to overwrite their managed backup directory.
 - PyCharm rolling selections preserve content offsets and flush pending wheel
   batches before mouse release.
@@ -190,8 +210,8 @@ contracts.
 - Camera and browser tools register only when their optional dependencies are
   present. Skill evolution and directive auto-learning are off by default and
   require explicit experimental environment gates.
-- The Example command is explicitly a teaching workflow; production profiles
-  use versioned Apps. The examples repository now exposes an `apps/` catalog
+- The Expert command is explicitly a teaching workflow; production profiles
+  use versioned Apps. The Expert repository now exposes an `apps/` catalog
   schema for Basic Chat, DashScope SDK Expert, and Bailian Expert.
 - Session events now project messages, plan, goal, artifacts, and unified
   runtime/agent/session/run/turn identifiers; forks replay the same state.

README.md

@@ -102,7 +102,7 @@ Do not paste real API keys into tracked configuration or example files.
 ```bash
 agenticx --cli                      # Inline REPL with terminal scrollback
 agenticx --tui                      # Textual interface (requires the TUI extra)
-agenticx "List the files in this directory and summarize the project"
+agenticx -c "List the files in this directory and summarize the project"
 ```
 
 Inside an interactive session:
@@ -190,6 +190,33 @@ agenticx app verify <app-name>
 agenticx app update <app-name>
 ```
 
+For example, install and verify DashScope SDK Expert from the official App
+Catalog:
+
+```bash
+python -m pip install "dashscope-agenticx>=1.0.1,<2"
+git clone https://github.com/dashscope/dashscope-agenticx-experts.git
+cd dashscope-agenticx-experts
+agenticx app install ./apps/dashscope-sdk-expert
+agenticx app info dashscope-sdk-expert
+agenticx app verify dashscope-sdk-expert
+```
+
+`app install` only installs and registers the versioned App under the current
+workspace's `.agenticx/apps/`; it does not activate the App profile. After the
+`cd` above, the cloned repository is that workspace. To run DashScope SDK Expert,
+merge its profile into the workspace and start AgenticX:
+
+```bash
+export DASHSCOPE_API_KEY="<your-api-key>"
+agenticx expert download dashscope-sdk-expert
+agenticx
+```
+
+Expert downloads are not registered as Apps and cannot be managed with `app
+list` or `app update`. `app update` reinstalls from the recorded source, so run
+`git pull` in the clone before updating a locally cloned App.
+
 The source tree includes `dashscope-sdk-expert` and `bailian-expert` bundles.
 Inspect the manifest and requested permissions before installation. A checksum
 proves content identity, not publisher authenticity; a local trust flag is not

README_zh.md

@@ -98,7 +98,7 @@ agenticx
 ```bash
 agenticx --cli
 agenticx --tui
-agenticx "列出当前目录的文件，并概述项目结构"
+agenticx -c "列出当前目录的文件，并概述项目结构"
 ```
 
 交互会话示例：
@@ -180,6 +180,31 @@ agenticx app verify <app-name>
 agenticx app update <app-name>
 ```
 
+例如，从官方 App Catalog 安装并校验 DashScope SDK Expert：
+
+```bash
+python -m pip install "dashscope-agenticx>=1.0.1,<2"
+git clone https://github.com/dashscope/dashscope-agenticx-experts.git
+cd dashscope-agenticx-experts
+agenticx app install ./apps/dashscope-sdk-expert
+agenticx app info dashscope-sdk-expert
+agenticx app verify dashscope-sdk-expert
+```
+
+`app install` 只将版本化 App 安装并登记到当前工作区的 `.agenticx/apps/`，
+不会启用 App Profile。上述 `cd` 之后，克隆仓库就是当前工作区。如需实际运行
+DashScope SDK Expert，将 Profile 合并到工作区后启动：
+
+```bash
+export DASHSCOPE_API_KEY="<your-api-key>"
+agenticx expert download dashscope-sdk-expert
+agenticx
+```
+
+Expert 下载不会登记为 App，不能用 `app list` 或 `app update` 管理。
+`app update` 从已记录的来源重新安装；更新本地克隆的 App 前，需先在克隆目录
+执行 `git pull`。
+
 源码提供 `dashscope-sdk-expert` 和 `bailian-expert` 两个 Bundle。
 安装前检查 Manifest 和请求的权限。Checksum 只能验证内容身份，不能证明发布者
 真实性；本地 trust 标记也不是经过验证的数字签名。

RELEASE.md

@@ -1,6 +1,6 @@
 # Release Process
 
-The release version is `1.0.0`. Updating the version and pushing or merging
+The release version is `1.0.1`. Updating the version and pushing or merging
 Git branches does not publish packages or create release tags. External
 publication requires the checks and explicit approval below.
 
@@ -15,7 +15,7 @@ publication requires the checks and explicit approval below.
    metadata, and `agenticx --version` agree.
 6. Only when external publication is explicitly approved, tag `v<version>` and
    publish the `dashscope-agenticx` wheel/sdist plus checksums and SBOM.
-7. Archive the migration guide and final benchmark/eval reports for `1.0.0`.
+7. Archive the migration guide and final benchmark/eval reports for `1.0.1`.
 
 Main-branch pushes and pull requests run unit tests and pre-commit checks.
 Before pushing a release tag, confirm the tagged source passed those checks.

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes target the active `1.0.0` release line.
+Security fixes target the active `1.0.1` release line.
 
 ## Reporting
 

migration-to-1.0.md

@@ -1,7 +1,7 @@
-# Migrating to DashScope AgenticX 1.0.0
+# Migrating to DashScope AgenticX 1.0.1
 
 This guide describes migration from legacy AgenticCLI versions to
-DashScope AgenticX `1.0.0`.
+DashScope AgenticX `1.0.1`.
 
 ## Current identities
 
@@ -23,8 +23,8 @@ DashScope AgenticX `1.0.0`.
 
 Expert downloads default to
 `https://github.com/dashscope/dashscope-agenticx-experts.git` on branch `main`.
-An explicit `examples_repo` setting or `--repo` flag can select another source.
-The catalog uses only `apps/<name>/`; legacy top-level example directories
+An explicit `expert_repo` setting or `--repo` flag can select another source.
+The catalog uses only `apps/<name>/`; legacy top-level Expert directories
 are not supported.
 
 ## One-way directory migration

scripts/release_check.py

@@ -25,7 +25,7 @@ def main() -> int:
     assert pyproject["project"]["scripts"] == {
         "agenticx": "dashscope_agenticx.cli:main",
     }
-    assert __version__ == "1.0.0"
+    assert __version__ == "1.0.1"
     assert (SRC / "dashscope_agenticx" / "py.typed").is_file()
     for legacy in ("agenticx", "agenticcli", "acli"):
         assert not (SRC / legacy).exists()

src/dashscope_agenticx/_version.py

@@ -1,4 +1,4 @@
 # -*- coding: utf-8 -*-
 """Single source of truth for package, CLI, SDK, and build versions."""
 
-__version__ = "1.0.0"
+__version__ = "1.0.1"

src/dashscope_agenticx/cli/__init__.py

@@ -54,8 +54,8 @@
     _handle_slash_command,
     dispatch_async_command,
 )
-from dashscope_agenticx.cli.examples import (  # noqa: E402
-    _handle_example_command,
+from dashscope_agenticx.cli.experts import (  # noqa: E402
+    _handle_expert_command,
 )
 from dashscope_agenticx.cli.handlers_capability import (  # noqa: F401,E402
     _cap_enabled,
@@ -241,8 +241,8 @@ def main():
             )
             asyncio.run(_run_oneshot(config, prompt))
             return
-        elif arg in ("expert", "experts", "example", "examples"):
-            _handle_example_command(sys.argv[2:])
+        elif arg == "expert":
+            _handle_expert_command(sys.argv[2:])
             return
         elif arg == "mcp-server":
             from dashscope_agenticx.mcp_server import main as _mcp_server_main

src/dashscope_agenticx/cli/completer.py

@@ -22,7 +22,7 @@
     _SUBCOMMANDS,
     _TOP_LEVEL_COMMANDS,
     CAPABILITY_CATALOG,
-    EXPERT_COMMAND_ALIASES,
+    EXPERT_COMMANDS,
 )
 from dashscope_agenticx.config import Config
 from dashscope_agenticx.skills import BUILTIN_SKILLS, KNOWN_MCP_SERVICES
@@ -222,13 +222,13 @@ def _slot_candidates(self, tokens: list[str], arg_index: int) -> list[str]:
         cmd = tokens[0]
 
         if (
-            cmd in EXPERT_COMMAND_ALIASES
+            cmd in EXPERT_COMMANDS
             and arg_index == 2
             and tokens[1] == "download"
         ):
-            from dashscope_agenticx.cli.examples import _KNOWN_EXAMPLES
+            from dashscope_agenticx.cli.experts import _KNOWN_EXPERTS
 
-            return list(_KNOWN_EXAMPLES)
+            return list(_KNOWN_EXPERTS)
 
         if cmd == "/skill" and arg_index == 1:
             return _SUBCOMMANDS["/skill"] + list(BUILTIN_SKILLS.keys())

src/dashscope_agenticx/cli/constants.py

@@ -184,7 +184,7 @@
 _MEDIA_SENTINEL_RE = re.compile(r"<<__AGENTICX_(IMG|AUDIO)_(\d+)__>>")
 
 # Top-level slash commands
-EXPERT_COMMAND_ALIASES = ("/expert", "/experts", "/example", "/examples")
+EXPERT_COMMANDS = ("/expert",)
 
 _TOP_LEVEL_COMMANDS = [
     "/help",
@@ -232,9 +232,6 @@
 # Static second-level subcommands
 _SUBCOMMANDS: dict[str, list[str]] = {
     "/expert": ["list", "download", "restore"],
-    "/experts": ["list", "download", "restore"],
-    "/example": ["list", "download", "restore"],
-    "/examples": ["list", "download", "restore"],
     "/capability": ["list", "enable", "disable", "reload", "config"],
     "/subagents": ["list", "reload", "enable", "disable", "config"],
     "/trust": ["list", "clear", "allow", "deny"],

src/dashscope_agenticx/cli/dispatch.py

@@ -15,7 +15,7 @@
 from dashscope_agenticx.cli.command_registry import (
     registry as command_registry,
 )
-from dashscope_agenticx.cli.constants import EXPERT_COMMAND_ALIASES
+from dashscope_agenticx.cli.constants import EXPERT_COMMANDS
 from dashscope_agenticx.cli.handlers_config import (
     _handle_debug_command,
     _handle_directives_command,
@@ -467,11 +467,11 @@ def _dispatch_slash_command(
     elif cmd.startswith("/directives"):
         _handle_directives_command(cmd, config)
         return True
-    elif cmd and cmd.split(maxsplit=1)[0] in EXPERT_COMMAND_ALIASES:
-        from dashscope_agenticx.cli.examples import _handle_example_command
+    elif cmd and cmd.split(maxsplit=1)[0] in EXPERT_COMMANDS:
+        from dashscope_agenticx.cli.experts import _handle_expert_command
 
         args = cmd.split()[1:]
-        _handle_example_command(args)
+        _handle_expert_command(args)
         return True
     elif cmd.startswith("/audit"):
         from dashscope_agenticx.audit import get_audit_logger