Skip to content

Commit 4a8e624

Browse files
AgentArcLabAgentArcLab
committed
docs: make Chinese README the default
1 parent a404f2e commit 4a8e624

2 files changed

Lines changed: 61 additions & 166 deletions

File tree

‎README.md‎

Lines changed: 43 additions & 151 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,22 @@
1-
# KsADK
1+
<h1 align="center">KsADK</h1>
22

3-
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/kingsoftcloud/ksadk-python)
3+
<p align="center"><strong>一次构建 Agent，到处运行。</strong></p>
44

5-
Build agents once. Run them anywhere.
5+
<p align="center">
6+
KsADK 是面向 AI Agent 的运行时平台（Agent Runtime Platform）。
7+
继续使用 Google ADK、LangGraph、LangChain 或 DeepAgents 编写业务 Agent，再用统一 CLI、Web UI、OpenAI-Compatible API、工具运行时、沙箱、部署和可观测链路把它跑起来。
8+
</p>
69

7-
KsADK 是面向 AI Agent 的 Agent Runtime Platform。你可以继续使用 Google ADK、LangGraph、LangChain 或 DeepAgents 编写业务 Agent，再用 KsADK 获得统一的本地运行、浏览器调试、OpenAI-Compatible API、沙箱执行、部署和可观测体验。
10+
<p align="center"><a href="README.md">简体中文（默认）</a> · <a href="README.en.md">English</a></p>
811

9-
当前源码版本：`0.6.6`。正式发布通过 GitHub Release 和 PyPI Trusted Publishing 提供。
12+
<p align="center">
13+
<a href="https://kingsoftcloud.github.io/ksadk-python/"><img alt="Docs" src="https://img.shields.io/badge/Docs-ksadk--python-2f6fdf?style=flat" /></a>
14+
<a href="https://pypi.org/project/ksadk/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ksadk?style=flat&color=2f6fdf" /></a>
15+
<a href="https://zread.ai/kingsoftcloud/ksadk-python"><img alt="Ask Zread" src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" /></a>
16+
<a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-blue?style=flat" /></a>
17+
</p>
1018

11-
## Why KsADK
12-
13-
Most agent frameworks solve agent development.
14-
15-
KsADK solves agent runtime.
16-
17-
KsADK 不替换你已经选择的 Agent 框架，而是在框架之上补齐运行时平台层：
18-
19-
- Development：统一 `agentengine init`、`agentengine config`、`agentengine run`。
20-
- Debugging：本地 Web UI、会话、附件、workspace 文件和流式输出。
21-
- Runtime：统一 Runner、OpenAI-Compatible API 和多框架入口。
22-
- Sandbox：Skill Runtime、Workspace 和 sandbox backend 的隔离执行边界。
23-
- Deployment：Serverless、Hermes、OpenClaw 和远端 AgentEngine 入口。
24-
- Observability：OpenTelemetry-first tracing，可对接多种观测后端。
25-
26-
Keep using your preferred framework. Get a complete runtime platform.
19+
<p align="center"><a href="public-docs/assets/ksadk-runtime-platform-hero.png"><img alt="KsADK 真实 CLI 截图：agentengine -h" src="public-docs/assets/ksadk-runtime-platform-hero-wide.png" width="860" /></a></p>
2720

2821
## 30 秒快速体验
2922

@@ -38,154 +31,53 @@ agentengine config set OPENAI_API_KEY=your-api-key OPENAI_MODEL_NAME=gpt-4o-mini
3831
agentengine run -i
3932
```
4033

41-
打开本地浏览器调试界面：
34+
启动本地调试 Web UI：
4235

4336
```bash
4437
agentengine web . --no-open
4538
```
4639

47-
如果你的模型服务不是默认 OpenAI endpoint，再额外配置：
48-
49-
```bash
50-
agentengine config set OPENAI_BASE_URL=https://api.example.com/v1
51-
```
52-
53-
如果需要调用金山云 AgentEngine、Skill Service、知识库或长期记忆等线上能力，建议显式设置线上默认地域：
54-
55-
```bash
56-
agentengine config set KSYUN_REGION=cn-beijing-6
57-
```
58-
59-
## Architecture
60-
61-
```text
62-
Agent Code
63-
ADK / LangGraph / LangChain / DeepAgents
64-
|
65-
v
66-
KsADK SDK
67-
runner adapters / config / toolsets
68-
|
69-
v
70-
Unified Runtime
71-
CLI / Web UI / OpenAI-Compatible API
72-
|
73-
+-- Skill Runtime
74-
+-- Workspace Tools
75-
+-- Sandbox Runtime
76-
+-- Memory & Knowledge
77-
|
78-
v
79-
AgentEngine
80-
Serverless / Hermes / OpenClaw Runtime
81-
```
82-
83-
## Supported Frameworks
84-
85-
| Framework | KsADK 负责什么 |
86-
| --- | --- |
87-
| Google ADK | 项目模板、Runner 适配、本地运行、Web UI 调试和部署入口。 |
88-
| LangGraph | 图状态入口、工具调用、streaming、Skill Runtime 和 workspace toolsets。 |
89-
| LangChain | Runnable/chain 适配、本地 OpenAI-Compatible API 和 tracing。 |
90-
| DeepAgents | 项目入口、运行时包装、浏览器调试和部署制品。 |
91-
92-
## Comparison
93-
94-
| Capability | ADK | LangGraph | OpenAI Agents SDK | KsADK |
95-
| --- | --- | --- | --- | --- |
96-
| Agent Development | Yes | Yes | Yes | Yes |
97-
| Browser Debugging UI | No | No | No | Yes |
98-
| Unified CLI | No | No | No | Yes |
99-
| OpenAI Compatible API | No | No | Partial | Yes |
100-
| Sandbox Runtime | No | No | No | Yes |
101-
| Deployment Workflow | No | No | No | Yes |
102-
| Multi Runtime Backend | No | No | No | Yes |
103-
104-
这张表只比较“项目自带的统一运行时平台能力”。KsADK 的设计目标不是替代这些框架，而是把它们放进同一套运行、调试、部署和观测体验里。
40+
<p align="center"><img alt="KsADK 真实 Web UI 调试截图" src="public-docs/assets/ksadk-web-ui-screenshot.png" width="860" /></p>
10541

106-
## Core Capabilities
42+
<p align="center"><img alt="KsADK 真实本地 Web UI 演示" src="public-docs/assets/ksadk-local-debugging-demo.gif" width="860" /></p>
10743

108-
- `agentengine init`：创建或导入 Agent 项目。
109-
- `agentengine config`：管理 `.env` 和 `agentengine.yaml`。
110-
- `agentengine run`：本地终端运行和交互调试。
111-
- `agentengine web`：启动本地 Web UI，验证 streaming、附件、workspace、工具调用和会话。
112-
- `/v1/responses` 与 `/v1/chat/completions`：提供 OpenAI-Compatible API。
113-
- `ksadk.toolsets`：提供 Skill、Workspace、Platform、Sandbox 内置工具。
114-
- Skill Runtime：发现、下载、校验、加载并隔离执行 Skill workflow。
115-
- Sandbox Runtime：通过可配置后端隔离执行命令或代码。
116-
- Hermes & OpenClaw：面向更完整 runtime 后端的部署和更新路径。
44+
## 为什么需要 KsADK
11745

118-
## Examples
46+
大多数 Agent 框架解决“如何开发 Agent”。KsADK 解决“如何运行、调试、部署和观测 Agent”。
11947

120-
样例仓库按场景组织，而不是只按技术框架分类：
48+
- 本地开发：`agentengine init`、`agentengine run`、`agentengine web`。
49+
- 统一调试：浏览器 Web UI、streaming、附件、workspace 文件、工具调用和会话。
50+
- 统一协议：本地 `/v1/responses` 与 `/v1/chat/completions`。
51+
- 工具边界：Skill Runtime、Workspace、Sandbox、Memory、Knowledge。
52+
- 工程链路：打包、部署、OpenTelemetry 可观测。
12153

122-
- [KSADK Samples](https://github.com/kingsoftcloud/ksadk-samples)
123-
- Knowledge Assistant：知识库问答和 RAG。
124-
- Workflow Agent：LangGraph + AgentEngine toolsets。
125-
- Tool-Using Agent：自定义工具调用。
126-
- Memory-aware Agent：短期记忆和长期记忆接入。
54+
## 架构
12755

128-
每个公开 demo 都应包含中文 README、运行命令、环境变量说明、降级行为和验证问题。
56+
<p align="center"><img alt="KsADK Agent Runtime Platform 架构" src="public-docs/assets/ksadk-runtime-architecture.png" width="860" /></p>
12957

130-
## Deployment
58+
## 文档与样例
13159

132-
KsADK 支持本地优先的开发路径，也提供经过审核后可使用的部署入口：
60+
- 文档：<https://kingsoftcloud.github.io/ksadk-python/>
61+
- 快速开始：<https://kingsoftcloud.github.io/ksadk-python/getting-started/quickstart/>
62+
- 为什么需要 KsADK：<https://kingsoftcloud.github.io/ksadk-python/getting-started/why-ksadk/>
63+
- 架构：<https://kingsoftcloud.github.io/ksadk-python/getting-started/architecture/>
64+
- 生态定位对比：<https://kingsoftcloud.github.io/ksadk-python/getting-started/comparison/>
65+
- 可观测：<https://kingsoftcloud.github.io/ksadk-python/guides/observability-tracing/>
66+
- 样例仓库：<https://github.com/kingsoftcloud/ksadk-samples>
13367

134-
```bash
135-
agentengine build .
136-
agentengine launch . --target serverless
137-
agentengine dashboard open
138-
```
68+
## 相关项目
13969

140-
Hermes 和 OpenClaw 更新已有实例时默认保留服务端已有 env、storage、network、memory 配置，只在显式传入对应 CLI 参数时覆盖，避免升级镜像时误改用户配置。
70+
- KsADK 仓库：<https://github.com/kingsoftcloud/ksadk-python>
71+
- Web UI 仓库：<https://github.com/kingsoftcloud/ksadk-web>
72+
- Wiki：<https://zread.ai/kingsoftcloud/ksadk-python>
73+
- PyPI：<https://pypi.org/project/ksadk/>
14174

142-
## Observability
75+
## 参与贡献
14376

144-
KsADK is OpenTelemetry-native.
77+
欢迎通过 issue、PR、样例和文档改进参与贡献。提交前建议运行：
14578

14679
```bash
147-
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel.example.com
148-
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20token
80+
make public-preflight
14981
```
15082

151-
Compatible with:
152-
153-
- Langfuse
154-
- Arize
155-
- Datadog
156-
- Grafana
157-
- Phoenix
158-
159-
Export once. Observe anywhere.
160-
161-
## 0.6.6 重点
162-
163-
- 统一模型策略 v1：默认主模型 `glm-5.2`、多模态模型 `kimi-k2.7-code`、fallback 模型 `deepseek-v4-pro`，Hermes、OpenClaw 和通用 Agent 使用同一套默认语义。
164-
- Hosted 附件内容恢复：本地 runtime 现在可以直接消费服务端 `ae-upload://...` 文件引用，并通过 `AttachmentContent` 恢复真实文件内容与本地缓存。
165-
- Hosted Workspace 导出修复：Workspace zip 下载通过受控 facade 转发到 runtime export，避免 share link / Hosted UI 下载目录时被公共 action 规则误拦截。
166-
- 会话与历史事件增强：`ListSessions` / `ListSessionEvents` 补齐分页与总数字段，本地 Web UI 支持更长历史会话列表和按需回加载旧事件。
167-
- Hosted TUI 会话复用：配合 `@kingsoftcloud/ksadk-web@0.2.11`，原生终端默认按当前业务会话复用 terminal session，并保留显式新建入口。
168-
- 长任务与终端验证脚本增强：新增 Hosted long-task、checkpoint resume、cancel/resume 和 terminal reconnect 验证脚本，发布前需结合目标环境完成 E2E。
169-
- CLI 与部署路径增强：dry-run JSON、no-cache、网络参数、环境变量覆盖、framework passthrough、远程 runner、A2A、Skill Runtime 和 sandbox 路径补齐回归覆盖。
170-
- 将公开定位从普通 SDK 调整为 Agent Runtime Platform，首页补齐 Why KsADK、30 秒体验、架构说明、Deployment、Observability 和 Community。
171-
- 清理 README、CHANGELOG 和后续 PyPI 元数据中的环境特定表述，避免公开页面出现内部环境名、内部 header 或私有 endpoint 示例。
172-
- 为公开定位、敏感词和 PyPI metadata 增加回归测试，防止后续回退。
173-
- 本地开发可从 `@kingsoftcloud/ksadk-web@latest` 同步 Web UI static；0.6.6 发布候选固定使用 `@kingsoftcloud/ksadk-web@0.2.11`，避免 npm `latest` 变化影响发布包。
174-
- PyPI 发布默认走 GitHub Actions Trusted Publishing，发布前按发布候选固定同步 KSADK Web static，并执行 `make public-preflight`。
175-
176-
## Documentation
177-
178-
- 文档：<https://kingsoftcloud.github.io/ksadk-python/>
179-
- 中文文档：<https://kingsoftcloud.github.io/ksadk-python/zh/>
180-
- English documentation：<https://kingsoftcloud.github.io/ksadk-python/en/>
181-
- 命令行参考：<https://kingsoftcloud.github.io/ksadk-python/reference/cli/>
182-
- OpenAI-Compatible API：<https://kingsoftcloud.github.io/ksadk-python/reference/openai-compatible-api/>
183-
184-
## Community
185-
186-
- 仓库：<https://github.com/kingsoftcloud/ksadk-python>
187-
- Wiki：<https://zread.ai/kingsoftcloud/ksadk-python>
188-
- 示例仓库：<https://github.com/kingsoftcloud/ksadk-samples>
189-
- Web UI 仓库：<https://github.com/kingsoftcloud/ksadk-web>
190-
- PyPI：<https://pypi.org/project/ksadk/>
191-
- 开源协议：Apache-2.0
83+
开源协议：Apache-2.0。

‎tests/test_public_release_positioning.py‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -26,30 +26,33 @@ def _changelog_section(version: str) -> str:
2626
def test_public_readme_positions_ksadk_as_runtime_platform():
2727
readme = _read("README.md")
2828
for expected in (
29-
"Build agents once. Run them anywhere.",
29+
"一次构建 Agent，到处运行。",
3030
"Agent Runtime Platform",
31-
"Why KsADK",
31+
"简体中文（默认）",
32+
"README.en.md",
3233
"30 秒快速体验",
33-
"Architecture",
34-
"Comparison",
35-
"Examples",
36-
"Deployment",
37-
"Observability",
38-
"Documentation",
39-
"Community",
40-
"KSYUN_REGION=cn-beijing-6",
34+
"为什么需要 KsADK",
35+
"KsADK 解决“如何运行、调试、部署和观测 Agent”",
36+
"文档与样例",
37+
"相关项目",
38+
"参与贡献",
4139
):
4240
assert expected in readme
4341

42+
english_readme = _read("README.en.md")
43+
for expected in (
44+
"Build agents once. Run them anywhere.",
45+
"Agent Runtime Platform",
46+
"30 Seconds Quick Start",
47+
"Why KsADK",
48+
"Docs And Examples",
49+
):
50+
assert expected in english_readme
51+
4452
assert "Agent Development Kit" not in readme
4553
assert "KSADK_SKILL_SERVICE_REGION=pre-online" not in readme
4654
assert "```mermaid" not in readme
47-
assert "```text" in readme
4855
assert "当前版本：" not in readme
49-
assert (
50-
"发布版本：`0.6.6`" in readme
51-
or "当前源码版本：`0.6.6`。正式发布通过 GitHub Release 和 PyPI Trusted Publishing 提供。" in readme
52-
)
5356

5457

5558
def test_public_metadata_uses_runtime_platform_positioning():

0 commit comments

Comments
 (0)