wboudiche/linshare

linshare 是做什么的？

linshare 是一个用于 LinShare 服务器（6.5 版本或更高）的命令行工具。用于安全地共享用户的文档。

首先，检查设置

在对话的第一次 LinShare 命令之前，运行 linshare --json whoami：

• 命令未找到（退出码 127）：未安装 linshare 命令。请用通俗的语言告知用户，此技能需要该命令，并且他们可以通过以下方式自行安装：pip install "git+https://github.com/wboudiche/linshare-cli#subdirectory=agent-harness"（需要 Python 3.10+）。请不要自行安装。
• 退出码 2（"code": "auth"）：未登录。请用户在此聊天中键入 ! linshare login --server <他们的 LinShare 地址>（如果你不知道地址，请询问用户）——他们在此处输入密码，切勿在对话中透露密码。 使用 SSO：! linshare login --token --server <地址>，从 Web 界面粘贴令牌。
• 退出码 0：显示服务器和账户信息；继续处理请求。

规则——每次都必须遵守

1. 始终在 linshare 后面加上 --json（linshare --json shares list）并读取 JSON。
2. 登录由用户完成，绝不由你进行。 如果命令以退出码 2（"code": "auth"）失败，请用户自行键入 ! linshare login（如果用户使用 SSO 登录并有来自 Web 界面的令牌，则为 ! linshare login --token）。切勿询问或键入其密码。
3. 在从账户中移出或销毁任何内容之前，必须获得明确的“是”。 这包括 share、request-files、shares revoke、documents delete、requests close，以及对于共享空间，还包括 spaces upload、spaces add-member、spaces set-role、spaces remove-member、spaces delete-files、spaces delete。
   • 对于 share 和 request-files：首先运行相同的命令并加上 --dry-run，然后用通俗的语言向用户展示： 文件（名称和大小）、每位收件人——标记 "external": true 的为 组织外部人员——到期日期、主题、消息、是否使用了密码保护链接，以及 downloadAlert/copyToMe（服务器实际将执行的操作：管理员的设置可能会覆盖用户的选择；如果 detail 中如此说明，请告知用户）。
   • 对于 revoke、delete、close：首先列出，然后精确显示哪些项目将受到影响。
   • 对于 spaces upload 和 spaces add-member：首先运行 --dry-run。对于上传，显示文件、工作组（和文件夹）以及 visibleTo——组内的所有成员都将看到这些文件（如果 visibleTo 为 null，则说明无法列出成员）。对于新成员，用通俗的语言显示人员（姓名和电子邮件）、空间及其角色（READER：只读，CONTRIBUTOR：可以添加，WRITER：可以添加和更改，ADMIN：还可管理成员）。
   • spaces delete 将删除空间及其所有文件（对每位成员都生效）；spaces delete-files 也会为所有人删除文件。请说明这一点，并指明空间和项目。
   • 仅使用用户为 --subject 和 --message 提供的词语。不要自行编写；可以省略，或建议一个并在用户同意后添加。 用于 request-files 的 --label 可以是取自用户话语的简短名称（例如“十月发票”）；如果没有提供，工具会默认选择“<你的邮箱> 的文件”。
   • request-files 需要 --message（LinShare 在没有消息时会拒绝请求）。如果用户未提供，请在试运行前询问用户消息内容；你可以提议一个措辞，但只有在用户接受后才使用。
   • 未提供到期时间（"expirationDate": null）表示使用服务器默认的到期时间，而非“永不过期”。
   • 等待明确的“是”。如果用户更改了任何内容（收件人、到期时间、文件），请重新运行 --dry-run 并再次询问。切勿重复使用之前的同意。
   • 在实际运行时，将试运行的 expirationDate 作为 --expires YYYY-MM-DD 传递（用户批准的确切日期），切勿再次使用像 7d 这样的相对值；--alert-if-not-downloaded 也同样处理（使用试运行的 alertIfNotDownloaded）。
4. 检查服务器，而非依赖记忆。 在告知用户某内容是否已共享、发送、撤销或关闭之前，运行相应的列表命令（shares list、requests list、documents list、spaces files、spaces members）。早期对话的记录可能已过时。
5. 只读命令无需确认： whoami、shares list、received list、received download、documents list、requests list、requests download、spaces list、spaces files、spaces members、spaces download。创建空的工作组或文件夹（spaces create、spaces mkdir）也无需确认：在未添加文件或成员之前，其他人看不到。
6. 共享后，告知用户哪些文件已发送给谁以及截止时间。 下载： LinShare 会在每位收件人首次下载共享文件时通过电子邮件通知发送者，并且 shares list 会显示 downloaded 计数——可用于回答“X 下载了吗？”。如需在文件未下载时收到警告，请使用 --alert-if-not-downloaded（一个日期、一个类似 3d 的延迟，或 off；如果不设置，则应用服务器默认值）。
7. 共享空间。 工作组存放团队共享的文件；工作空间则对工作组进行分组。 命令使用 ID：运行 spaces list 查找空间，运行 spaces files SPACE [--folder ID] 查找文件夹或文件。多个空间可能同名：如果用户的话语匹配多个空间，请询问是哪一个。通过电子邮件共享文件（share）和将其放入工作组（spaces upload）是不同的操作：如果不清楚，请询问。 在 LinShare 7.0 上，由于服务器错误，某些功能可能失败：spaces members 无法列出成员（请使用 add-member 打印的成员 ID 进行 set-role/remove-member），并且无法将人员添加到工作空间（只能添加到其工作组）。请将错误信息转述给用户；不要尝试其他方法重试。
8. 出错时，用通俗的语言转述 error.message。未经询问，不要使用其他设置重试被拒绝的共享。退出码 1 表示命令本身有误（请修正，而非要求用户登录）。当共享失败时，工具会删除已上传的文件并告知用户；如果 error.code 是 "timeout"，则结果未知——请遵循提示（检查 shares list/documents list），然后再进行任何重试。
9. 大文件没问题：超过 2 MiB 的文件，工具会像 Web 界面一样分块发送。上传速度在快速网络上约为每 GB 15 秒，在慢速网络上则更慢。对于超过几百 MB 的文件，请为 share 命令设置较长的超时时间（或在后台运行），以免被中断，并告知用户这可能需要一些时间。

典型流程

linshare --json share ./contract.pdf --to [email protected] --expires 7d --message "请签字" --dry-run
# → 向用户展示摘要，等待“是”
# 试运行显示 "expirationDate": "2026-11-13"
linshare --json share ./contract.pdf --to [email protected] --expires 2026-11-13 --message "请签字"

命令

命令	功能	需要先确认？
linshare login [--server URL] [--email E]	用户一次性登录（密码，如需要则输入 2FA 验证码）	用户自行运行
linshare login --token [--server URL]	用户粘贴在 LinShare Web 界面生成的令牌	用户自行运行
linshare logout	遗忘（并撤销）令牌	否
linshare whoami	显示正在使用的服务器和账户	否
linshare share FILE... --to EMAIL... [--expires 7d|2w|1m|YYYY-MM-DD] [--subject S] [--message M] [--password-link] [--alert-if-not-downloaded WHEN] [--send-me-a-copy] [--dry-run]	上传并通过电子邮件共享	是
linshare shares list	列出用户共享的内容	否
linshare shares revoke ID...	取消共享	是
linshare received list	列出其他人共享给用户的内容	否
linshare received download ID [--out DIR]	保存收到的文件（从不覆盖）	否
linshare documents list	列出用户的文档	否
linshare documents delete ID...	删除文档	是
linshare request-files --from EMAIL... --message M [--label L] [--expires ...] [--dry-run]	请求他人发送文件（每人一个私有请求）	是
linshare requests list	列出上传请求和已收到的文件	否
linshare requests download ID [--out DIR]	以 zip 形式下载收到的文件	否
linshare requests close ID...	关闭请求	是
linshare spaces list [--in WORKSPACE]	列出工作组和工作空间，以及你的角色	否
linshare spaces create NAME [--workspace] [--in WORKSPACE]	创建工作组（或工作空间）	否
linshare spaces delete ID...	删除空间及其所有文件，对所有人生效	是
linshare spaces files SPACE [--folder ID]	列出工作组的文件夹和文件	否
linshare spaces mkdir SPACE NAME [--folder ID]	创建文件夹	否
linshare spaces upload SPACE FILE... [--folder ID] [--dry-run]	将文件放入工作组（成员可见）	是
linshare spaces download SPACE ID [--out DIR]	保存工作组文件（从不覆盖）	否
linshare spaces delete-files SPACE ID...	删除文件或文件夹，对所有人生效	是
linshare spaces members SPACE	列出成员及其角色	否
linshare spaces add-member SPACE EMAIL --role R [--dry-run]	授予某人访问权限	是
linshare spaces set-role SPACE MEMBER ROLE	更改角色（MEMBER：电子邮件或成员 ID）	是
linshare spaces remove-member SPACE MEMBER	移除访问权限	是

--to 和 --from 可重复用于多人：--to [email protected] --to [email protected]。 “外部”是一种启发式判断：指与用户不同的电子邮件域名。

退出码

0 正常 · 1 输入错误或命令错误 · 2 未登录/登录问题 · 3 服务器拒绝 · 4 服务器不可达、故障或过慢（"code": "timeout"）。