guands

观远 BI 数据源/数据集管理工具，支持连接账号管理、数据集创建/配置/刷新、增量设置、定时更新、目录管理。

本地安装（开发/测试阶段）

# 编译所有平台 binary（需要 Go 工具链）
npm run build

# 安装到本地 node global
npm link

安装后即可在终端使用：

guands account list
guands dataset list
guands dataset create-db --ac-id <acId> --tables "t1,t2"
guands dataset refresh <dsId> --wait
guands dataset schedule <dsId> --cron-type daily --hour 2 --minute 0
guands dataset create-db --ac-id <acId> --tables "t1,t2" --wait

说明：npm 包名为 @guandata/guands，用户侧 CLI 命令统一为 guands。

也可以为 AI Coding Assistant 安装 Skill：

guands install-skill

npm install -g --foreground-scripts @guandata/guands / npm link --foreground-scripts 会通过 postinstall 自动刷新 skill，并显示明确的成功、失败或跳过结果；上述 guands install-skill 仅用于失败后的手动修复或排查。CI 等无需 skill 的环境可设 GUAN_SKIP_INSTALL_SKILL=1 跳过。

安装包会通过 npm optionalDependencies 自动选择当前系统的原生二进制。不要使用 --omit=optional 或 optional=false；企业 npm 镜像也需要同步对应的 @guandata/guands-<平台>-<架构> 包。若平台包缺失，CLI 会显示对应包名和重新安装方法。

版本更新

@guandata/guands 0.1.35

• 安装时自动选择当前系统和架构的原生程序，减少下载量与磁盘占用，原有安装命令不变；离线安装也支持自动选包。

@guandata/guands 0.1.34

• 同步本次发布的内部依赖更新，无用户可见行为变化。

@guandata/guands 0.1.33

• 同步共享鉴权与环境识别更新，支持识别内部 OAuth2 应用认证环境。

@guandata/guands 0.1.32

• 新建数据集要求指定目标目录并确认落位计划，完成后返回访问链接和存储路径。
• 追加或替换数据需要 --yes，不支持的 WebService 写操作会安全拒绝。
• 执行等待改为按数据集 ID 跟踪，并修复嵌套表单和日期时间格式处理。

@guandata/guands 0.1.31

• form create -f json 返回可直接解析的表单 ID、名称、目录、字段数和访问路径。
• 修复 Windows npm 全局安装场景下的 CLI 执行器定位问题。

@guandata/guands 0.1.30

• GUAN_FORM 支持通过 sync-schema 原地同步 Form 字段变化，保留数据集和字段引用。
• schema 提交后严格回读字段集合、类型、字段 ID 和数据集状态，失败时提供明确恢复路径。
• SurveyEngine 423 错误提示更准确，便于区分权限、功能和资源状态问题。

@guandata/guands 0.1.29

• 建集后返回真实抽数任务 ID，并修复数据账号列表和异步大结果表清单读取。
• 调度新增 cron 与 ETL 存在性预检，任务不存在会立即返回真实错误。
• 批量删除、移动和设置更新不再掩盖单项失败或服务端未采纳结果。
• 计算字段写操作新增存在性校验，结构化错误和退出状态更适合自动化判断。

@guandata/guands 0.1.28

• 新增 calc-field apply，可协调新增、更新和保留计算字段，减少重复创建。
• 完善数据集目录创建、改名和删除能力，并修复目录改名失败问题。
• 建库与查询数据集创建在失败时会返回正确退出状态，便于自动化流程及时停止。
• 修复参数引用误判，并增强写操作的错误保真与网络兼容性。

@guandata/guands 0.1.27

• 修复数据集中存在派生字段时，CSV 追加或替换可能误判 Schema 的问题。
• 改进 Skill 自动安装反馈、删除确认和 Windows CLI 兼容性。
• 补充文件上传超时配置说明，便于适配大文件或较慢网络。

@guandata/guands 0.1.26

• 增强填报数据集结构同步能力，提升结构变更场景下的同步稳定性。
• 修复表单原样更新时数字格式未正确补入的问题。

@guandata/guands 0.1.25

• 数据集目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标目录。
• 更新底层依赖，提升安全性和运行稳定性。

@guandata/guands 0.1.24

• 填报表单支持创建 TABLE 子表及子表字段，复杂表单可以由 Agent 完整生成。
• 支持保真迁移空选项下拉和使用系统保留名的业务字段，导出后再更新不会丢失原有配置。

@guandata/guands 0.1.23

• 数据连接配置支持安全原地更新，可先预览并校验变更，同时保护已有敏感配置。
• 填报表单支持导出、编辑和重命名，更新时保留已有字段与数据。
• 新增填报表单目录管理和表单移动能力，便于整理业务表单。

@guandata/guands 0.1.22

• 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
• 随包提供完整的数据源和数据集操作说明与参考资料。

@guandata/guands 0.1.21

• 数据集导入默认等待任务完成并返回真实结果，同时会提前识别扩展名与内容不一致的文件，减少异步失败和乱码数据集。
• Excel 导入、追加和替换数据支持明确选择 Sheet；单 Sheet 自动选择，多 Sheet 必须指定一个，避免隐式合并造成数据错误。
• 新增独立的数据集主键设置与清空能力，修改后会等待数据重写任务完成并回读验证。

@guandata/guands 0.1.20

• 数据连接账号支持安全原地改名，保留账号 ID、凭证、权限和已有数据集引用，并在更新后自动回读确认。
• 数据集刷新会识别和跟随已有更新任务，避免重复提交；等待、覆盖刷新和任务失败后的最终状态判断更准确。
• 增强资源 ID 校验和创建结果解析，写操作输出契约更清晰，便于 Agent 稳定获取新建资源并继续后续操作。

@guandata/guands 0.1.19

• 数据集支持追加数据和按条件/全量清理数据，便于维护 CSV/Excel 导入类数据集。
• 新增数据集 schema 同步、自动同步结构开关和字段更新预校验，减少源表结构变化后的手工处理成本。
• 支持批量新增计算字段，并增强分组字段、字段展示名和字段来源识别能力。
• 支持从填报表单创建数据集，并可查看数据集行列权限配置。
• 增强数据集目录校验、依赖提示、任务历史和抽数结果诊断，提升批量建集、刷新和排障体验。

@guandata/guands 0.1.18

• dataset import 支持按列指定字段类型，导入 CSV/Excel 时可更准确地控制字段解析结果。
• dataset replace-data 增加 --encoding 和 --delimiter，替换数据时可处理更多文件编码和分隔符格式。
• 导入参数校验会忽略未导入列的类型提示，减少按列配置时的误报。

@guandata/guands 0.1.17

• install-skill 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

@guandata/guands 0.1.16

• dataset list 统一使用目录搜索接口，提升目录筛选和列表结果的一致性。

@guandata/guands 0.1.15

• 新增 dataset update-fields，支持批量更新数据集字段展示名和注释，可通过命令行参数或 JSON 文件提交，并支持 --dry-run 预览请求体。
• dataset import 增加 --header-row、--encoding、--delimiter，并在导入前识别单列解析异常，降低 CSV/Excel 导入参数误配风险。
• 修复 replace-data 处理 UTF-8 BOM 表头时的 schema 校验误判；account columns 默认使用账号配置中的 schema/database。
• 修复 dataset batch-move、save-as 等数据集请求参数，并为 refresh 增加 --overwrite 全量覆盖模式。

@guandata/guands 0.1.14

• dataset alias 支持更新数据集字段展示名，便于为新版 ETL 输入列名做准备和验证。

@guandata/guands 0.1.13

• install-skill 增加 WorkBuddy skill 安装路径支持。

0.1.12

• 优化试用账号场景下的运行上下文识别，提升命令执行记录与问题排查的一致性。
• 重新构建发布产物，纳入共享运行上下文处理更新。

卸载

npm unlink -g @guandata/guands

支持平台

• macOS (Apple Silicon / Intel)
• Windows (x64)

开发

# 编译所有平台 binary（需要 Go 工具链）
npm run build